# HG changeset patch # User Mike Becker # Date 1526472179 -7200 # Node ID 348fd9cb7b14ed80141af8a91d0e4fb1b64e099d # Parent ebae0e434898aa88216bfdcd34830d37871d6a76 adds remaining documentation for the scstr functions diff -r ebae0e434898 -r 348fd9cb7b14 src/string.c --- a/src/string.c Wed May 16 13:13:33 2018 +0200 +++ b/src/string.c Wed May 16 14:02:59 2018 +0200 @@ -201,8 +201,8 @@ return ret; } -scstr_t scstrsubs(scstr_t s, size_t start) { - return scstrsubsl (s, start, s.length-start); +scstr_t scstrsubs(scstr_t string, size_t start) { + return scstrsubsl(string, start, string.length-start); } scstr_t scstrsubsl(scstr_t s, size_t start, size_t length) { @@ -215,9 +215,9 @@ } -int ucx_strchr(const char *string, size_t length, int chr, size_t *pos) { +static int ucx_strchr(const char *str, size_t length, int chr, size_t *pos) { for(size_t i=0;i 0) { for(size_t i=length ; i>0 ; i--) { - if(string[i-1] == chr) { + if(str[i-1] == chr) { *pos = i-1; return 1; } @@ -278,7 +278,7 @@ } while (0); -const char* ucx_strstr( +static const char* ucx_strstr( const char *str, size_t length, const char *match, @@ -511,11 +511,11 @@ } } -sstr_t scstrdup(scstr_t s) { +sstr_t ucx_strdup(scstr_t s) { return sstrdup_a(ucx_default_allocator(), s); } -sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t s) { +sstr_t ucx_strdup_a(UcxAllocator *allocator, scstr_t s) { sstr_t newstring; newstring.ptr = (char*)almalloc(allocator, s.length + 1); if (newstring.ptr) { @@ -531,7 +531,7 @@ } -size_t ucx_strtrim(const char *s, size_t len, size_t *newlen) { +static size_t ucx_strtrim(const char *s, size_t len, size_t *newlen) { const char *newptr = s; size_t length = len; diff -r ebae0e434898 -r 348fd9cb7b14 src/ucx/string.h --- a/src/ucx/string.h Wed May 16 13:13:33 2018 +0200 +++ b/src/ucx/string.h Wed May 16 14:02:59 2018 +0200 @@ -255,19 +255,26 @@ /** * Returns the cumulated length of all specified strings. - * - * At least one string must be specified. + * + * You may arbitrarily mix up mutable (sstr_t) and immutable + * (scstr_t) strings. * * Attention: if the count argument does not match the count of the * specified strings, the behavior is undefined. * * @param count the total number of specified strings (so at least 1) - * @param string the first string - * @param ... all other strings + * @param ... all strings * @return the cumulated length of all strings */ size_t ucx_strnlen(size_t count, ...); +/** + * Alias for ucx_strnlen(). + * + * @param count the total number of specified strings (so at least 1) + * @param ... all strings + * @return the cumulated length of all strings + */ #define sstrnlen(count, ...) ucx_strnlen(count, __VA_ARGS__) /** @@ -286,6 +293,14 @@ */ sstr_t ucx_strcat(size_t count, scstr_t s1, ...); +/** + * Alias for ucx_strcat() which automatically casts the first string. + * + * @param count the total number of strings to concatenate + * @param s1 first string + * @param ... all remaining strings + * @return the concatenated string + */ #define sstrcat(count, s1, ...) ucx_strcat(count, SCSTR(s1), __VA_ARGS__) /** @@ -301,7 +316,19 @@ */ sstr_t ucx_strcat_a(UcxAllocator *a, size_t count, scstr_t s1, ...); -#define sstrcat_a(count, s1, ...) ucx_strcat_a(count, SCSTR(s1), __VA_ARGS__) +/** + * Alias for ucx_strcat_a() which automatically casts the first string. + * + * See sstrcat() for details. + * + * @param a the allocator to use + * @param count the total number of strings to concatenate + * @param s1 first string + * @param ... all remaining strings + * @return the concatenated string + */ +#define sstrcat_a(a, count, s1, ...) \ + ucx_strcat_a(a, count, SCSTR(s1), __VA_ARGS__) /** * Returns a substring starting at the specified location. @@ -337,13 +364,42 @@ */ sstr_t sstrsubsl(sstr_t string, size_t start, size_t length); -scstr_t scstrsubs(scstr_t s, size_t start); +/** + * Returns a substring of an immutable string starting at the specified + * location. + * + * Attention: the new string references the same memory area as the + * input string and will NOT be NULL-terminated. + * Use scstrdup() to get a copy. + * + * @param string input string + * @param start start location of the substring + * @return a substring of string starting at start + * + * @see scstrsubsl() + * @see scstrchr() + */ +scstr_t scstrsubs(scstr_t string, size_t start); + +/** + * Returns a substring of an immutable string with a maximum length starting + * at the specified location. + * + * Attention: the new string references the same memory area as the + * input string and will NOT be NULL-terminated. + * Use scstrdup() to get a copy. + * + * @param string input string + * @param start start location of the substring + * @param length the maximum length of the substring + * @return a substring of string starting at start + * with a maximum length of length + * + * @see scstrsubs() + * @see scstrchr() + */ scstr_t scstrsubsl(scstr_t string, size_t start, size_t length); - -int ucx_strchr(const char *string, size_t length, int chr, size_t *pos); -int ucx_strrchr(const char *string, size_t length, int chr, size_t *pos); - /** * Returns a substring starting at the location of the first occurrence of the * specified character. @@ -372,17 +428,34 @@ */ sstr_t sstrrchr(sstr_t string, int chr); +/** + * Returns an immutable substring starting at the location of the first + * occurrence of the specified character. + * + * If the string does not contain the character, an empty string is returned. + * + * @param string the string where to locate the character + * @param chr the character to locate + * @return a substring starting at the first location of chr + * + * @see scstrsubs() + */ +scstr_t scstrchr(scstr_t string, int chr); -scstr_t scstrchr(scstr_t string, int chr); +/** + * Returns an immutable substring starting at the location of the last + * occurrence of the specified character. + * + * If the string does not contain the character, an empty string is returned. + * + * @param string the string where to locate the character + * @param chr the character to locate + * @return a substring starting at the last location of chr + * + * @see scstrsubs() + */ scstr_t scstrrchr(scstr_t string, int chr); -const char* ucx_strstr( - const char *str, - size_t length, - const char *match, - size_t matchlen, - size_t *newlen); - /** * Returns a substring starting at the location of the first occurrence of the * specified string. @@ -399,9 +472,44 @@ * present in string */ sstr_t ucx_sstrstr(sstr_t string, scstr_t match); + +/** + * Alias for ucx_sstrstr() which automatically casts the match string. + * + * @param string the string to be scanned + * @param match string containing the sequence of characters to match + * @return a substring starting at the first occurrence of + * match, or an empty string, if the sequence is not + * present in string + */ #define sstrstr(string, match) ucx_sstrstr(string, SCSTR(match)) +/** + * Returns an immutable substring starting at the location of the + * first occurrence of the specified immutable string. + * + * If the string does not contain the other string, an empty string is returned. + * + * If match is an empty string, the complete string is + * returned. + * + * @param string the string to be scanned + * @param match string containing the sequence of characters to match + * @return a substring starting at the first occurrence of + * match, or an empty string, if the sequence is not + * present in string + */ scstr_t ucx_scstrstr(scstr_t string, scstr_t match); + +/** + * Alias for ucx_scstrstr() which automatically casts the match string. + * + * @param string the string to be scanned + * @param match string containing the sequence of characters to match + * @return a substring starting at the first occurrence of + * match, or an empty string, if the sequence is not + * present in string + */ #define scstrstr(string, match) ucx_scstrstr(string, SCSTR(match)) /** @@ -447,13 +555,26 @@ * @param count IN: the maximum size of the resulting array (0 = no limit), * OUT: the actual size of the array * @return a sstr_t array containing the split strings or - * NULL on error + * NULL on error + * + * @see ucx_strsplit_a() + */ +sstr_t* ucx_strsplit(scstr_t string, scstr_t delim, ssize_t *count); + +/** + * Alias for ucx_strsplit() which automatically casts the arguments. + * + * @param string the string to split + * @param delim the delimiter string + * @param count IN: the maximum size of the resulting array (0 = no limit), + * OUT: the actual size of the array + * @return a sstr_t array containing the split strings or + * NULL on error * * @see sstrsplit_a() */ -sstr_t* ucx_strsplit(scstr_t string, scstr_t delim, ssize_t *count); - -#define sstrsplit(s, delim, count) ucx_strsplit(SCSTR(s), SCSTR(delim), count) +#define sstrsplit(string, delim, count) \ + ucx_strsplit(SCSTR(string), SCSTR(delim), count) /** * Performing sstrsplit() using a UcxAllocator. @@ -473,19 +594,33 @@ * @param count IN: the maximum size of the resulting array (0 = no limit), * OUT: the actual size of the array * @return a sstr_t array containing the split strings or - * NULL on error + * NULL on error * - * @see sstrsplit() + * @see ucx_strsplit() */ sstr_t* ucx_strsplit_a(UcxAllocator *allocator, scstr_t string, scstr_t delim, ssize_t *count); -#define sstrsplit_a(a, s, d, c) ucx_strsplit_a(a, SCSTR(s), SCSTR(d, c)) +/** + * Alias for ucx_strsplit_a() which automatically casts the arguments. + * + * @param allocator the UcxAllocator used for allocating memory + * @param string the string to split + * @param delim the delimiter string + * @param count IN: the maximum size of the resulting array (0 = no limit), + * OUT: the actual size of the array + * @return a sstr_t array containing the split strings or + * NULL on error + * + * @see sstrsplit() + */ +#define sstrsplit_a(allocator, string, delim, count) \ + ucx_strsplit_a(allocator, SCSTR(string), SCSTR(delim, count)) /** * Compares two UCX strings with standard memcmp(). * - * At first it compares the sstr_t.length attribute of the two strings. The + * At first it compares the scstr_t.length attribute of the two strings. The * memcmp() function is called, if and only if the lengths match. * * @param s1 the first string @@ -496,6 +631,15 @@ */ int ucx_strcmp(scstr_t s1, scstr_t s2); +/** + * Alias for ucx_strcmp() which automatically casts its arguments. + * + * @param s1 the first string + * @param s2 the second string + * @return -1, if the length of s1 is less than the length of s2 or 1, if the + * length of s1 is greater than the length of s2 or the result of + * memcmp() otherwise (i.e. 0 if the strings match) + */ #define sstrcmp(s1, s2) ucx_strcmp(SCSTR(s1), SCSTR(s2)) /** @@ -508,12 +652,20 @@ * @param s1 the first string * @param s2 the second string * @return -1, if the length of s1 is less than the length of s2 or 1, if the - * length of s1 is greater than the length of s2 or the difference between the - * first two differing characters otherwise (i.e. 0 if the strings match and - * no characters differ) + * length of s1 is greater than the length of s2 or the result of the platform + * specific string comparison function ignoring the case. */ int ucx_strcasecmp(scstr_t s1, scstr_t s2); +/** + * Alias for ucx_strcasecmp() which automatically casts the arguments. + * + * @param s1 the first string + * @param s2 the second string + * @return -1, if the length of s1 is less than the length of s2 or 1, if the + * length of s1 is greater than the length of s2 or the result of the platform + * specific string comparison function ignoring the case. + */ #define sstrcasecmp(s1, s2) ucx_strcasecmp(SCSTR(s1), SCSTR(s2)) /** @@ -524,15 +676,22 @@ * free(). * * The sstr_t.ptr of the return value will always be NULL- - * terminated and mutable. + * terminated and mutable, regardless of the argument. + * + * @param string the string to duplicate + * @return a duplicate of the string + * @see ucx_strdup_a() + */ +sstr_t ucx_strdup(scstr_t string); + +/** + * Alias for ucx_strdup() which automatically casts the argument. * * @param string the string to duplicate * @return a duplicate of the string * @see sstrdup_a() */ -sstr_t scstrdup(scstr_t string); - -#define sstrdup(s) scstrdup(SCSTR(s)) +#define sstrdup(string) ucx_strdup(SCSTR(string)) /** * Creates a duplicate of the specified string using a UcxAllocator. @@ -543,20 +702,26 @@ * ucx_allocator_free function manually. * * The sstr_t.ptr of the return value will always be NULL- - * terminated. + * terminated and mutable, regardless of the argument. * * @param allocator a valid instance of a UcxAllocator * @param string the string to duplicate * @return a duplicate of the string - * @see sstrdup() + * @see ucx_strdup() */ -sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t string); +sstr_t ucx_strdup_a(UcxAllocator *allocator, scstr_t string); -#define sstrdup_a(allocator, s) scstrdup_a(allocator, SCSTR(s)) +/** + * Alias for ucx_strdup_a() which automatically casts the argument. + * + * @param allocator a valid instance of a UcxAllocator + * @param string the string to duplicate + * @return a duplicate of the string + * @see ucx_strdup() + */ +#define sstrdup_a(allocator, string) ucx_strdup_a(allocator, SCSTR(string)) -size_t ucx_strtrim(const char *str, size_t length, size_t *newlen); - /** * Omits leading and trailing spaces. * @@ -576,6 +741,23 @@ */ sstr_t sstrtrim(sstr_t string); +/** + * Omits leading and trailing spaces. + * + * This function returns a new scstr_t containing a trimmed version of the + * specified string. + * + * Note: the new scstr_t references the same memory, thus you + * MUST NOT pass the scstr_t.ptr of the return value to + * free(). It is also highly recommended to avoid assignments like + * mystr = scstrtrim(mystr); as you lose the reference to the + * source string. Assignments of this type are only permitted, if the + * scstr_t.ptr of the source string does not need to be freed or if another + * reference to the source string exists. + * + * @param string the string that shall be trimmed + * @return a new scstr_t containing the trimmed string + */ scstr_t scstrtrim(scstr_t string); /** @@ -586,6 +768,13 @@ */ int ucx_strprefix(scstr_t string, scstr_t prefix); +/** + * Alias for ucx_strprefix() which automatically casts the arguments. + * + * @param string the string to check + * @param prefix the prefix the string should have + * @return 1, if and only if the string has the specified prefix, 0 otherwise + */ #define sstrprefix(string, prefix) ucx_strprefix(SCSTR(string), SCSTR(prefix)) /** @@ -596,64 +785,98 @@ */ int ucx_strsuffix(scstr_t string, scstr_t suffix); -#define sstrsuffix(string, prefix) ucx_strsuffix(SCSTR(string), SCSTR(prefix)) +/** + * Alias for ucx_strsuffix() which automatically casts the arguments. + * + * @param string the string to check + * @param suffix the suffix the string should have + * @return 1, if and only if the string has the specified suffix, 0 otherwise + */ +#define sstrsuffix(string, suffix) ucx_strsuffix(SCSTR(string), SCSTR(suffix)) /** * Returns a lower case version of a string. * * This function creates a duplicate of the input string, first. See the - * documentation of sstrdup() for the implications. + * documentation of scstrdup() for the implications. * * @param string the input string * @return the resulting lower case string - * @see sstrdup() + * @see scstrdup() */ sstr_t ucx_strlower(scstr_t string); +/** + * Alias for ucx_strlower() which automatically casts the argument. + * + * @param string the input string + * @return the resulting lower case string + */ #define sstrlower(string) ucx_strlower(SCSTR(string)) /** * Returns a lower case version of a string. * * This function creates a duplicate of the input string, first. See the - * documentation of sstrdup_a() for the implications. + * documentation of scstrdup_a() for the implications. * * @param allocator the allocator used for duplicating the string * @param string the input string * @return the resulting lower case string - * @see sstrdup_a() + * @see scstrdup_a() */ sstr_t ucx_strlower_a(UcxAllocator *allocator, scstr_t string); + +/** + * Alias for ucx_strlower_a() which automatically casts the argument. + * + * @param allocator the allocator used for duplicating the string + * @param string the input string + * @return the resulting lower case string + */ #define sstrlower_a(allocator, string) ucx_strlower_a(allocator, SCSTR(string)) /** * Returns a upper case version of a string. * * This function creates a duplicate of the input string, first. See the - * documentation of sstrdup() for the implications. + * documentation of scstrdup() for the implications. * * @param string the input string * @return the resulting upper case string - * @see sstrdup() + * @see scstrdup() */ sstr_t ucx_strupper(scstr_t string); +/** + * Alias for ucx_strupper() which automatically casts the argument. + * + * @param string the input string + * @return the resulting upper case string + */ #define sstrupper(string) ucx_strupper(SCSTR(string)) /** * Returns a upper case version of a string. * * This function creates a duplicate of the input string, first. See the - * documentation of sstrdup_a() for the implications. + * documentation of scstrdup_a() for the implications. * * @param allocator the allocator used for duplicating the string * @param string the input string * @return the resulting upper case string - * @see sstrdup_a() + * @see scstrdup_a() */ sstr_t ucx_strupper_a(UcxAllocator *allocator, scstr_t string); +/** + * Alias for ucx_strupper_a() which automatically casts the argument. + * + * @param allocator the allocator used for duplicating the string + * @param string the input string + * @return the resulting upper case string + */ #define sstrupper_a(allocator, string) ucx_strupper_a(allocator, string) #ifdef __cplusplus