Mercurial > hg > ucx / changeset

--- 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<length;i++) {
-        if(string[i] == chr) {
+        if(str[i] == chr) {
             *pos = i;
             return 1;
         }
@@ -225,10 +225,10 @@
     return 0;
 }
 
-int ucx_strrchr(const char *string, size_t length, int chr, size_t *pos) {
+static int ucx_strrchr(const char *str, size_t length, int chr, size_t *pos) {
     if(length > 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;
     

--- 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 (<code>sstr_t</code>) and immutable
+ * (<code>scstr_t</code>) strings.
  * 
  * <b>Attention:</b> 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,12 +364,41 @@
  */
 sstr_t sstrsubsl(sstr_t string, size_t start, size_t length);
 
-scstr_t scstrsubs(scstr_t s, size_t start);
-scstr_t scstrsubsl(scstr_t string, size_t start, size_t length);
+/**
+ * Returns a substring of an immutable string starting at the specified
+ * location.
+ * 
+ * <b>Attention:</b> the new string references the same memory area as the
+ * input string and will <b>NOT</b> be <code>NULL</code>-terminated.
+ * Use scstrdup() to get a copy.
+ * 
+ * @param string input string
+ * @param start  start location of the substring
+ * @return a substring of <code>string</code> starting at <code>start</code>
+ * 
+ * @see scstrsubsl()
+ * @see scstrchr()
+ */
+scstr_t scstrsubs(scstr_t string, size_t start);
 
-
-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 of an immutable string with a maximum length starting
+ * at the specified location.
+ * 
+ * <b>Attention:</b> the new string references the same memory area as the
+ * input string and will <b>NOT</b> be <code>NULL</code>-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 <code>string</code> starting at <code>start</code>
+ * with a maximum length of <code>length</code>
+ * 
+ * @see scstrsubs()
+ * @see scstrchr()
+ */
+scstr_t scstrsubsl(scstr_t string, size_t start, size_t length);
 
 /**
  * Returns a substring starting at the location of the first occurrence of the
@@ -372,16 +428,33 @@
  */
 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 <code>chr</code>
+ * 
+ * @see scstrsubs()
+ */
 scstr_t scstrchr(scstr_t string, int chr);
-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 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 <code>chr</code>
+ * 
+ * @see scstrsubs()
+ */
+scstr_t scstrrchr(scstr_t string, int chr);
 
 /**
  * Returns a substring starting at the location of the first occurrence of the
@@ -399,9 +472,44 @@
  *               present in <code>string</code>
  */
 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
+ *               <code>match</code>, or an empty string, if the sequence is not
+ *               present in <code>string</code>
+ */
 #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 <code>match</code> is an empty string, the complete <code>string</code> 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
+ *               <code>match</code>, or an empty string, if the sequence is not
+ *               present in <code>string</code>
+ */
 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
+ *               <code>match</code>, or an empty string, if the sequence is not
+ *               present in <code>string</code>
+ */
 #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
- *         <code>NULL</code> on error
+ * <code>NULL</code> 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
+ * <code>NULL</code> 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
- *         <code>NULL</code> on error
+ * <code>NULL</code> 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
+ * <code>NULL</code> 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 <code>memcmp()</code>.
  * 
- * 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
  * <code>memcmp()</code> 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
+ * <code>memcmp()</code> 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 @@
  * <code>free()</code>.
  * 
  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
- * 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 <i>always</i> be <code>NULL</code>-
- * 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.
+ * 
+ * <b>Note:</b> the new scstr_t references the same memory, thus you
+ * <b>MUST NOT</b> pass the scstr_t.ptr of the return value to
+ * <code>free()</code>. It is also highly recommended to avoid assignments like
+ * <code>mystr = scstrtrim(mystr);</code> 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