From 91ed5c392de70e05b3a4b89487bb4eacde8efdd5 Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Fri, 16 Feb 2024 10:41:15 -0500 Subject: [PATCH] Marks as private several functions in our header files. (#600) * Marks as private several functions in our header files. * format --- include/ada/character_sets-inl.h | 5 +++++ include/ada/character_sets.h | 3 +++ include/ada/checkers.h | 14 ++++++++++++++ include/ada/helpers.h | 6 ++++++ include/ada/unicode-inl.h | 4 ++++ include/ada/unicode.h | 25 +++++++++++++++++++++++++ 6 files changed, 57 insertions(+) diff --git a/include/ada/character_sets-inl.h b/include/ada/character_sets-inl.h index 14ad76d41..1813f4927 100644 --- a/include/ada/character_sets-inl.h +++ b/include/ada/character_sets-inl.h @@ -9,6 +9,11 @@ #include "ada/character_sets.h" +/** + * These functions are not part of our public API and may + * change at any time. + * @private + */ namespace ada::character_sets { constexpr char hex[1024] = diff --git a/include/ada/character_sets.h b/include/ada/character_sets.h index 02adbed07..5728f31cc 100644 --- a/include/ada/character_sets.h +++ b/include/ada/character_sets.h @@ -11,6 +11,9 @@ #include /** + * These functions are not part of our public API and may + * change at any time. + * @private * @namespace ada::character_sets * @brief Includes the definitions for unicode character sets. */ diff --git a/include/ada/checkers.h b/include/ada/checkers.h index 2bf543990..8442e998a 100644 --- a/include/ada/checkers.h +++ b/include/ada/checkers.h @@ -11,12 +11,16 @@ #include /** + * These functions are not part of our public API and may + * change at any time. + * @private * @namespace ada::checkers * @brief Includes the definitions for validation functions */ namespace ada::checkers { /** + * @private * Assuming that x is an ASCII letter, this function returns the lower case * equivalent. * @details More likely to be inlined by the compiler and constexpr. @@ -24,6 +28,7 @@ namespace ada::checkers { constexpr char to_lower(char x) noexcept; /** + * @private * Returns true if the character is an ASCII letter. Equivalent to std::isalpha * but more likely to be inlined by the compiler. * @@ -32,6 +37,7 @@ constexpr char to_lower(char x) noexcept; constexpr bool is_alpha(char x) noexcept; /** + * @private * Check whether a string starts with 0x or 0X. The function is only * safe if input.size() >=2. * @@ -39,17 +45,20 @@ constexpr bool is_alpha(char x) noexcept; */ inline bool has_hex_prefix_unsafe(std::string_view input); /** + * @private * Check whether a string starts with 0x or 0X. */ inline bool has_hex_prefix(std::string_view input); /** + * @private * Check whether x is an ASCII digit. More likely to be inlined than * std::isdigit. */ constexpr bool is_digit(char x) noexcept; /** + * @private * @details A string starts with a Windows drive letter if all of the following * are true: * @@ -63,6 +72,7 @@ constexpr bool is_digit(char x) noexcept; inline constexpr bool is_windows_drive_letter(std::string_view input) noexcept; /** + * @private * @details A normalized Windows drive letter is a Windows drive letter of which * the second code point is U+003A (:). */ @@ -70,12 +80,14 @@ inline constexpr bool is_normalized_windows_drive_letter( std::string_view input) noexcept; /** + * @private * @warning Will be removed when Ada requires C++20. */ ada_really_inline bool begins_with(std::string_view view, std::string_view prefix); /** + * @private * Returns true if an input is an ipv4 address. It is assumed that the string * does not contain uppercase ASCII characters (the input should have been * lowered cased before calling this function) and is not empty. @@ -83,6 +95,7 @@ ada_really_inline bool begins_with(std::string_view view, ada_really_inline ada_constexpr bool is_ipv4(std::string_view view) noexcept; /** + * @private * Returns a bitset. If the first bit is set, then at least one character needs * percent encoding. If the second bit is set, a \\ is found. If the third bit * is set then we have a dot. If the fourth bit is set, then we have a percent @@ -92,6 +105,7 @@ ada_really_inline constexpr uint8_t path_signature( std::string_view input) noexcept; /** + * @private * Returns true if the length of the domain name and its labels are according to * the specifications. The length of the domain must be 255 octets (253 * characters not including the last 2 which are the empty label reserved at the diff --git a/include/ada/helpers.h b/include/ada/helpers.h index 0a4454282..c500966f6 100644 --- a/include/ada/helpers.h +++ b/include/ada/helpers.h @@ -13,6 +13,9 @@ #include /** + * These functions are not part of our public API and may + * change at any time. + * * @private * @namespace ada::helpers * @brief Includes the definitions for helper functions @@ -175,6 +178,7 @@ inline void inner_concat(std::string& buffer, T t, Args... args) { } /** + * @private * Concatenate the arguments and return a string. * @returns a string */ @@ -186,6 +190,7 @@ std::string concat(Args... args) { } /** + * @private * @return Number of leading zeroes. */ inline int leading_zeroes(uint32_t input_num) noexcept { @@ -199,6 +204,7 @@ inline int leading_zeroes(uint32_t input_num) noexcept { } /** + * @private * Counts the number of decimal digits necessary to represent x. * faster than std::to_string(x).size(). * @return digit count diff --git a/include/ada/unicode-inl.h b/include/ada/unicode-inl.h index 8145bdb7a..7bbbd8fe3 100644 --- a/include/ada/unicode-inl.h +++ b/include/ada/unicode-inl.h @@ -8,6 +8,10 @@ #include "ada/unicode.h" /** + * Unicode operations. These functions are not part of our public API and may + * change at any time. + * + * private * @namespace ada::unicode * @brief Includes the declarations for unicode operations */ diff --git a/include/ada/unicode.h b/include/ada/unicode.h index 2a98adb20..278ad260b 100644 --- a/include/ada/unicode.h +++ b/include/ada/unicode.h @@ -12,12 +12,17 @@ #include /** + * Unicode operations. These functions are not part of our public API and may + * change at any time. + * + * @private * @namespace ada::unicode * @brief Includes the definitions for unicode operations */ namespace ada::unicode { /** + * @private * We receive a UTF-8 string representing a domain name. * If the string is percent encoded, we apply percent decoding. * @@ -61,11 +66,13 @@ bool to_ascii(std::optional& out, std::string_view plain, size_t first_percent); /** + * @private * @see https://www.unicode.org/reports/tr46/#ToUnicode */ std::string to_unicode(std::string_view input); /** + * @private * Checks if the input has tab or newline characters. * * @attention The has_tabs_or_newline function is a bottleneck and it is simple @@ -75,12 +82,14 @@ ada_really_inline bool has_tabs_or_newline( std::string_view user_input) noexcept; /** + * @private * Checks if the input is a forbidden host code point. * @see https://url.spec.whatwg.org/#forbidden-host-code-point */ ada_really_inline constexpr bool is_forbidden_host_code_point(char c) noexcept; /** + * @private * Checks if the input contains a forbidden domain code point. * @see https://url.spec.whatwg.org/#forbidden-domain-code-point */ @@ -88,6 +97,7 @@ ada_really_inline constexpr bool contains_forbidden_domain_code_point( const char* input, size_t length) noexcept; /** + * @private * Checks if the input contains a forbidden domain code point in which case * the first bit is set to 1. If the input contains an upper case ASCII letter, * then the second bit is set to 1. @@ -98,6 +108,7 @@ contains_forbidden_domain_code_point_or_upper(const char* input, size_t length) noexcept; /** + * @private * Checks if the input is a forbidden domain code point. * @see https://url.spec.whatwg.org/#forbidden-domain-code-point */ @@ -105,11 +116,13 @@ ada_really_inline constexpr bool is_forbidden_domain_code_point( char c) noexcept; /** + * @private * Checks if the input is alphanumeric, '+', '-' or '.' */ ada_really_inline constexpr bool is_alnum_plus(char c) noexcept; /** + * @private * @details An ASCII hex digit is an ASCII upper hex digit or ASCII lower hex * digit. An ASCII upper hex digit is an ASCII digit or a code point in the * range U+0041 (A) to U+0046 (F), inclusive. An ASCII lower hex digit is an @@ -118,6 +131,7 @@ ada_really_inline constexpr bool is_alnum_plus(char c) noexcept; ada_really_inline constexpr bool is_ascii_hex_digit(char c) noexcept; /** + * @private * Checks if the input is a C0 control or space character. * * @details A C0 control or space is a C0 control or U+0020 SPACE. @@ -127,6 +141,7 @@ ada_really_inline constexpr bool is_ascii_hex_digit(char c) noexcept; ada_really_inline constexpr bool is_c0_control_or_space(char c) noexcept; /** + * @private * Checks if the input is a ASCII tab or newline character. * * @details An ASCII tab or newline is U+0009 TAB, U+000A LF, or U+000D CR. @@ -134,6 +149,7 @@ ada_really_inline constexpr bool is_c0_control_or_space(char c) noexcept; ada_really_inline constexpr bool is_ascii_tab_or_newline(char c) noexcept; /** + * @private * @details A double-dot path segment must be ".." or an ASCII case-insensitive * match for ".%2e", "%2e.", or "%2e%2e". */ @@ -141,6 +157,7 @@ ada_really_inline ada_constexpr bool is_double_dot_path_segment( std::string_view input) noexcept; /** + * @private * @details A single-dot path segment must be "." or an ASCII case-insensitive * match for "%2e". */ @@ -148,17 +165,20 @@ ada_really_inline constexpr bool is_single_dot_path_segment( std::string_view input) noexcept; /** + * @private * @details ipv4 character might contain 0-9 or a-f character ranges. */ ada_really_inline constexpr bool is_lowercase_hex(char c) noexcept; /** + * @private * @details Convert hex to binary. Caller is responsible to ensure that * the parameter is an hexadecimal digit (0-9, A-F, a-f). */ ada_really_inline unsigned constexpr convert_hex_to_binary(char c) noexcept; /** + * @private * first_percent should be = input.find('%') * * @todo It would be faster as noexcept maybe, but it could be unsafe since. @@ -169,12 +189,14 @@ ada_really_inline unsigned constexpr convert_hex_to_binary(char c) noexcept; std::string percent_decode(std::string_view input, size_t first_percent); /** + * @private * Returns a percent-encoding string whether percent encoding was needed or not. * @see https://github.com/nodejs/node/blob/main/src/node_url.cc#L226 */ std::string percent_encode(std::string_view input, const uint8_t character_set[]); /** + * @private * Returns a percent-encoded string version of input, while starting the percent * encoding at the provided index. * @see https://github.com/nodejs/node/blob/main/src/node_url.cc#L226 @@ -182,6 +204,7 @@ std::string percent_encode(std::string_view input, std::string percent_encode(std::string_view input, const uint8_t character_set[], size_t index); /** + * @private * Returns true if percent encoding was needed, in which case, we store * the percent-encoded content in 'out'. If the boolean 'append' is set to * true, the content is appended to 'out'. @@ -192,12 +215,14 @@ template bool percent_encode(std::string_view input, const uint8_t character_set[], std::string& out); /** + * @private * Returns the index at which percent encoding should start, or (equivalently), * the length of the prefix that does not require percent encoding. */ ada_really_inline size_t percent_encode_index(std::string_view input, const uint8_t character_set[]); /** + * @private * Lowers the string in-place, assuming that the content is ASCII. * Return true if the content was ASCII. */