diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
commit | 9e365069afe156f33fadfad9705e1325f894cd54 (patch) | |
tree | 78373044d029feb51f987b45208e0c1a36958625 /source/blender/blenlib/intern/string.c | |
parent | d8b42751625c915113b64f5a2d9c72f19f009fee (diff) |
Cleanup: move public doc-strings into headers for 'blenlib'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenlib/intern/string.c')
-rw-r--r-- | source/blender/blenlib/intern/string.c | 312 |
1 files changed, 0 insertions, 312 deletions
diff --git a/source/blender/blenlib/intern/string.c b/source/blender/blenlib/intern/string.c index 62c8625378d..35711c9432f 100644 --- a/source/blender/blenlib/intern/string.c +++ b/source/blender/blenlib/intern/string.c @@ -42,15 +42,6 @@ // #define DEBUG_STRSIZE -/** - * Duplicates the first \a len bytes of cstring \a str - * into a newly mallocN'd string and returns it. \a str - * is assumed to be at least len bytes long. - * - * \param str: The string to be duplicated - * \param len: The number of bytes to duplicate - * \retval Returns the duplicated string - */ char *BLI_strdupn(const char *str, const size_t len) { char *n = MEM_mallocN(len + 1, "strdup"); @@ -60,24 +51,11 @@ char *BLI_strdupn(const char *str, const size_t len) return n; } -/** - * Duplicates the cstring \a str into a newly mallocN'd - * string and returns it. - * - * \param str: The string to be duplicated - * \retval Returns the duplicated string - */ char *BLI_strdup(const char *str) { return BLI_strdupn(str, strlen(str)); } -/** - * Appends the two strings, and returns new mallocN'ed string - * \param str1: first string for copy - * \param str2: second string for append - * \retval Returns dst - */ char *BLI_strdupcat(const char *__restrict str1, const char *__restrict str2) { /* include the NULL terminator of str2 only */ @@ -95,16 +73,6 @@ char *BLI_strdupcat(const char *__restrict str1, const char *__restrict str2) return str; } -/** - * Like strncpy but ensures dst is always - * '\0' terminated. - * - * \param dst: Destination for copy - * \param src: Source string to copy - * \param maxncpy: Maximum number of characters to copy (generally - * the size of dst) - * \retval Returns dst - */ char *BLI_strncpy(char *__restrict dst, const char *__restrict src, const size_t maxncpy) { size_t srclen = BLI_strnlen(src, maxncpy - 1); @@ -119,16 +87,6 @@ char *BLI_strncpy(char *__restrict dst, const char *__restrict src, const size_t return dst; } -/** - * Like BLI_strncpy but ensures dst is always padded by given char, - * on both sides (unless src is empty). - * - * \param dst: Destination for copy - * \param src: Source string to copy - * \param pad: the char to use for padding - * \param maxncpy: Maximum number of characters to copy (generally the size of dst) - * \retval Returns dst - */ char *BLI_strncpy_ensure_pad(char *__restrict dst, const char *__restrict src, const char pad, @@ -171,19 +129,6 @@ char *BLI_strncpy_ensure_pad(char *__restrict dst, return dst; } -/** - * Like strncpy but ensures dst is always - * '\0' terminated. - * - * \note This is a duplicate of #BLI_strncpy that returns bytes copied. - * And is a drop in replacement for 'snprintf(str, sizeof(str), "%s", arg);' - * - * \param dst: Destination for copy - * \param src: Source string to copy - * \param maxncpy: Maximum number of characters to copy (generally - * the size of dst) - * \retval The number of bytes copied (The only difference from BLI_strncpy). - */ size_t BLI_strncpy_rlen(char *__restrict dst, const char *__restrict src, const size_t maxncpy) { size_t srclen = BLI_strnlen(src, maxncpy - 1); @@ -205,9 +150,6 @@ size_t BLI_strcpy_rlen(char *__restrict dst, const char *__restrict src) return srclen; } -/** - * Portable replacement for `vsnprintf`. - */ size_t BLI_vsnprintf(char *__restrict buffer, size_t maxncpy, const char *__restrict format, @@ -231,9 +173,6 @@ size_t BLI_vsnprintf(char *__restrict buffer, return n; } -/** - * A version of #BLI_vsnprintf that returns `strlen(buffer)` - */ size_t BLI_vsnprintf_rlen(char *__restrict buffer, size_t maxncpy, const char *__restrict format, @@ -258,9 +197,6 @@ size_t BLI_vsnprintf_rlen(char *__restrict buffer, return n; } -/** - * Portable replacement for #snprintf - */ size_t BLI_snprintf(char *__restrict dst, size_t maxncpy, const char *__restrict format, ...) { size_t n; @@ -277,9 +213,6 @@ size_t BLI_snprintf(char *__restrict dst, size_t maxncpy, const char *__restrict return n; } -/** - * A version of #BLI_snprintf that returns `strlen(dst)` - */ size_t BLI_snprintf_rlen(char *__restrict dst, size_t maxncpy, const char *__restrict format, ...) { size_t n; @@ -296,10 +229,6 @@ size_t BLI_snprintf_rlen(char *__restrict dst, size_t maxncpy, const char *__res return n; } -/** - * Print formatted string into a newly #MEM_mallocN'd string - * and return it. - */ char *BLI_sprintfN(const char *__restrict format, ...) { DynStr *ds; @@ -318,18 +247,6 @@ char *BLI_sprintfN(const char *__restrict format, ...) return n; } -/** - * This roughly matches C and Python's string escaping with double quotes - `"`. - * - * Since every character may need escaping, - * it's common to create a buffer twice as large as the input. - * - * \param dst: The destination string, at least \a dst_maxncpy, typically `(strlen(src) * 2) + 1`. - * \param src: The un-escaped source string. - * \param dst_maxncpy: The maximum number of bytes allowable to copy. - * - * \note This is used for creating animation paths in blend files. - */ size_t BLI_str_escape(char *__restrict dst, const char *__restrict src, const size_t dst_maxncpy) { @@ -381,18 +298,6 @@ BLI_INLINE bool str_unescape_pair(char c_next, char *r_out) return false; } -/** - * This roughly matches C and Python's string escaping with double quotes - `"`. - * - * The destination will never be larger than the source, it will either be the same - * or up to half when all characters are escaped. - * - * \param dst: The destination string, at least the size of `strlen(src) + 1`. - * \param src: The escaped source string. - * \param src_maxncpy: The maximum number of bytes allowable to copy from `src`. - * \param dst_maxncpy: The maximum number of bytes allowable to copy into `dst`. - * \param r_is_complete: Set to true when - */ size_t BLI_str_unescape_ex(char *__restrict dst, const char *__restrict src, const size_t src_maxncpy, @@ -418,16 +323,6 @@ size_t BLI_str_unescape_ex(char *__restrict dst, return len; } -/** - * See #BLI_str_unescape_ex doc-string. - * - * This function makes the assumption that `dst` always has - * at least `src_maxncpy` bytes available. - * - * Use #BLI_str_unescape_ex if `dst` has a smaller fixed size. - * - * \note This is used for parsing animation paths in blend files (runs often). - */ size_t BLI_str_unescape(char *__restrict dst, const char *__restrict src, const size_t src_maxncpy) { size_t len = 0; @@ -442,14 +337,6 @@ size_t BLI_str_unescape(char *__restrict dst, const char *__restrict src, const return len; } -/** - * Find the first un-escaped quote in the string (to find the end of the string). - * - * \param str: Typically this is the first character in a quoted string. - * Where the character before `*str` would be `"`. - - * \return The pointer to the first un-escaped quote. - */ const char *BLI_str_escape_find_quote(const char *str) { bool escape = false; @@ -462,18 +349,6 @@ const char *BLI_str_escape_find_quote(const char *str) return (*str == '"') ? str : NULL; } -/** - * Return the range of the quoted string (excluding quotes) `str` after `prefix`. - * - * A version of #BLI_str_quoted_substrN that calculates the range - * instead of un-escaping and allocating the result. - * - * \param str: String potentially including `prefix`. - * \param prefix: Quoted string prefix. - * \param r_start: The start of the quoted string (after the first quote). - * \param r_end: The end of the quoted string (before the last quote). - * \return True when a quoted string range could be found after `prefix`. - */ bool BLI_str_quoted_substr_range(const char *__restrict str, const char *__restrict prefix, int *__restrict r_start, @@ -539,19 +414,6 @@ char *BLI_str_quoted_substrN(const char *__restrict str, const char *__restrict } #endif -/** - * Fills \a result with text within "" that appear after some the contents of \a prefix. - * i.e. for string `pose["apples"]` with prefix `pose[`, it will return `apples`. - * - * \param str: is the entire string to chop. - * \param prefix: is the part of the string to step over. - * \param result: The buffer to fill. - * \param result_maxlen: The maximum size of the buffer (including nil terminator). - * \return True if the prefix was found and the entire quoted string was copied into result. - * - * Assume that the strings returned must be freed afterwards, - * and that the inputs will contain data we want. - */ bool BLI_str_quoted_substr(const char *__restrict str, const char *__restrict prefix, char *result, @@ -570,19 +432,6 @@ bool BLI_str_quoted_substr(const char *__restrict str, return is_complete; } -/** - * string with all instances of substr_old replaced with substr_new, - * Returns a copy of the c-string \a str into a newly #MEM_mallocN'd - * and returns it. - * - * \note A rather wasteful string-replacement utility, though this shall do for now... - * Feel free to replace this with an even safe + nicer alternative - * - * \param str: The string to replace occurrences of substr_old in - * \param substr_old: The text in the string to find and replace - * \param substr_new: The text in the string to find and replace - * \retval Returns the duplicated string - */ char *BLI_str_replaceN(const char *__restrict str, const char *__restrict substr_old, const char *__restrict substr_new) @@ -638,13 +487,6 @@ char *BLI_str_replaceN(const char *__restrict str, return BLI_strdup(str); } -/** - * In-place replace every \a src to \a dst in \a str. - * - * \param str: The string to operate on. - * \param src: The character to replace. - * \param dst: The character to replace with. - */ void BLI_str_replace_char(char *str, char src, char dst) { while (*str) { @@ -655,13 +497,6 @@ void BLI_str_replace_char(char *str, char src, char dst) } } -/** - * Simple exact-match string replacement. - * - * \param replace_table: Array of source, destination pairs. - * - * \note Larger tables should use a hash table. - */ bool BLI_str_replace_table_exact(char *string, const size_t string_len, const char *replace_table[][2], @@ -678,19 +513,11 @@ bool BLI_str_replace_table_exact(char *string, /** \} */ -/** - * Compare two strings without regard to case. - * - * \retval True if the strings are equal, false otherwise. - */ int BLI_strcaseeq(const char *a, const char *b) { return (BLI_strcasecmp(a, b) == 0); } -/** - * Portable replacement for `strcasestr` (not available in MSVC) - */ char *BLI_strcasestr(const char *s, const char *find) { char c, sc; @@ -745,9 +572,6 @@ bool BLI_string_all_words_matched(const char *name, return all_words_matched; } -/** - * Variation of #BLI_strcasestr with string length limited to \a len - */ char *BLI_strncasestr(const char *s, const char *find, size_t len) { char c, sc; @@ -875,10 +699,6 @@ static int left_number_strcmp(const char *s1, const char *s2, int *tiebreaker) return 0; } -/** - * Case insensitive, *natural* string comparison, - * keeping numbers in order. - */ int BLI_strcasecmp_natural(const char *s1, const char *s2) { int d1 = 0, d2 = 0; @@ -946,10 +766,6 @@ int BLI_strcasecmp_natural(const char *s1, const char *s2) return strcmp(s1, s2); } -/** - * Like strcmp, but will ignore any heading/trailing pad char for comparison. - * So e.g. if pad is '*', '*world' and 'world*' will compare equal. - */ int BLI_strcmp_ignore_pad(const char *str1, const char *str2, const char pad) { size_t str1_len, str2_len; @@ -990,7 +806,6 @@ int BLI_strcmp_ignore_pad(const char *str1, const char *str2, const char pad) } } -/* determine the length of a fixed-size string */ size_t BLI_strnlen(const char *s, const size_t maxlen) { size_t len; @@ -1025,9 +840,6 @@ void BLI_str_toupper_ascii(char *str, const size_t len) } } -/** - * Strip white-space from end of the string. - */ void BLI_str_rstrip(char *str) { for (int i = (int)strlen(str) - 1; i >= 0; i--) { @@ -1040,15 +852,6 @@ void BLI_str_rstrip(char *str) } } -/** - * Strip trailing zeros from a float, eg: - * 0.0000 -> 0.0 - * 2.0010 -> 2.001 - * - * \param str: - * \param pad: - * \return The number of zeros stripped. - */ int BLI_str_rstrip_float_zero(char *str, const char pad) { char *p = strchr(str, '.'); @@ -1069,14 +872,6 @@ int BLI_str_rstrip_float_zero(char *str, const char pad) return totstrip; } -/** - * Return index of a string in a string array. - * - * \param str: The string to find. - * \param str_array: Array of strings. - * \param str_array_len: The length of the array, or -1 for a NULL-terminated array. - * \return The index of str in str_array or -1. - */ int BLI_str_index_in_array_n(const char *__restrict str, const char **__restrict str_array, const int str_array_len) @@ -1092,13 +887,6 @@ int BLI_str_index_in_array_n(const char *__restrict str, return -1; } -/** - * Return index of a string in a string array. - * - * \param str: The string to find. - * \param str_array: Array of strings, (must be NULL-terminated). - * \return The index of str in str_array or -1. - */ int BLI_str_index_in_array(const char *__restrict str, const char **__restrict str_array) { int index; @@ -1112,13 +900,6 @@ int BLI_str_index_in_array(const char *__restrict str, const char **__restrict s return -1; } -/** - * Find if a string starts with another string. - * - * \param str: The string to search within. - * \param start: The string we look for at the start. - * \return If str starts with start. - */ bool BLI_str_startswith(const char *__restrict str, const char *__restrict start) { for (; *str && *start; str++, start++) { @@ -1146,61 +927,22 @@ bool BLI_strn_endswith(const char *__restrict str, const char *__restrict end, s return false; } -/** - * Find if a string ends with another string. - * - * \param str: The string to search within. - * \param end: The string we look for at the end. - * \return If str ends with end. - */ bool BLI_str_endswith(const char *__restrict str, const char *__restrict end) { const size_t slength = strlen(str); return BLI_strn_endswith(str, end, slength); } -/** - * Find the first char matching one of the chars in \a delim, from left. - * - * \param str: The string to search within. - * \param delim: The set of delimiters to search for, as unicode values. - * \param sep: Return value, set to the first delimiter found (or NULL if none found). - * \param suf: Return value, set to next char after the first delimiter found - * (or NULL if none found). - * \return The length of the prefix (i.e. *sep - str). - */ size_t BLI_str_partition(const char *str, const char delim[], const char **sep, const char **suf) { return BLI_str_partition_ex(str, NULL, delim, sep, suf, false); } -/** - * Find the first char matching one of the chars in \a delim, from right. - * - * \param str: The string to search within. - * \param delim: The set of delimiters to search for, as unicode values. - * \param sep: Return value, set to the first delimiter found (or NULL if none found). - * \param suf: Return value, set to next char after the first delimiter found - * (or NULL if none found). - * \return The length of the prefix (i.e. *sep - str). - */ size_t BLI_str_rpartition(const char *str, const char delim[], const char **sep, const char **suf) { return BLI_str_partition_ex(str, NULL, delim, sep, suf, true); } -/** - * Find the first char matching one of the chars in \a delim, either from left or right. - * - * \param str: The string to search within. - * \param end: If non-NULL, the right delimiter of the string. - * \param delim: The set of delimiters to search for, as unicode values. - * \param sep: Return value, set to the first delimiter found (or NULL if none found). - * \param suf: Return value, set to next char after the first delimiter found - * (or NULL if none found). - * \param from_right: If %true, search from the right of \a str, else, search from its left. - * \return The length of the prefix (i.e. *sep - str). - */ size_t BLI_str_partition_ex(const char *str, const char *end, const char delim[], @@ -1275,14 +1017,6 @@ static size_t BLI_str_format_int_grouped_ex(char src[16], char dst[16], int num_ return (size_t)(p_dst - dst); } -/** - * Format ints with decimal grouping. - * 1000 -> 1,000 - * - * \param dst: The resulting string - * \param num: Number to format - * \return The length of \a dst - */ size_t BLI_str_format_int_grouped(char dst[16], int num) { char src[16]; @@ -1291,14 +1025,6 @@ size_t BLI_str_format_int_grouped(char dst[16], int num) return BLI_str_format_int_grouped_ex(src, dst, num_len); } -/** - * Format uint64_t with decimal grouping. - * 1000 -> 1,000 - * - * \param dst: The resulting string - * \param num: Number to format - * \return The length of \a dst - */ size_t BLI_str_format_uint64_grouped(char dst[16], uint64_t num) { /* NOTE: Buffer to hold maximum unsigned int64, which is 1.8e+19. but @@ -1309,16 +1035,6 @@ size_t BLI_str_format_uint64_grouped(char dst[16], uint64_t num) return BLI_str_format_int_grouped_ex(src, dst, num_len); } -/** - * Format a size in bytes using binary units. - * 1000 -> 1 KB - * Number of decimal places grows with the used unit (e.g. 1.5 MB, 1.55 GB, 1.545 TB). - * - * \param dst: The resulting string. - * Dimension of 14 to support largest possible value for \a bytes (#LLONG_MAX). - * \param bytes: Number to format. - * \param base_10: Calculate using base 10 (GB, MB, ...) or 2 (GiB, MiB, ...). - */ void BLI_str_format_byte_unit(char dst[15], long long int bytes, const bool base_10) { double bytes_converted = bytes; @@ -1345,24 +1061,6 @@ void BLI_str_format_byte_unit(char dst[15], long long int bytes, const bool base BLI_strncpy(dst + len, base_10 ? units_base_10[order] : units_base_2[order], dst_len - len); } -/** - * Format a count to up to 6 places (plus '\0' terminator) string using long number - * names abbreviations. Used to produce a compact representation of large numbers. - * - * 1 -> 1 - * 15 -> 15 - * 155 -> 155 - * 1555 -> 1.6K - * 15555 -> 15.6K - * 155555 -> 156K - * 1555555 -> 1.6M - * 15555555 -> 15.6M - * 155555555 -> 156M - * 1000000000 -> 1B - * ... - * - * Length of 7 is the maximum of the resulting string, for example, `-15.5K\0`. - */ void BLI_str_format_attribute_domain_size(char dst[7], int number_to_format) { float number_to_format_converted = number_to_format; @@ -1384,16 +1082,6 @@ void BLI_str_format_attribute_domain_size(char dst[7], int number_to_format) BLI_snprintf(dst, dst_len, "%.*f%s", decimals, number_to_format_converted, units[order]); } -/** - * Find the ranges needed to split \a str into its individual words. - * - * \param str: The string to search for words. - * \param len: Size of the string to search. - * \param delim: Character to use as a delimiter. - * \param r_words: Info about the words found. Set to [index, len] pairs. - * \param words_max: Max number of words to find - * \return The number of words found in \a str - */ int BLI_string_find_split_words( const char *str, const size_t len, const char delim, int r_words[][2], int words_max) { |