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