ucx: comparison src/ucx/string.h

-:ebae0e434898
+:348fd9cb7b14
 */
 scstr_t scstrn(const char *cstring, size_t length);
 /**
 * 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 strings
-* @param ...      all other 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__)
 /**
 * Concatenates two or more strings.
 *
 * @param ...     all remaining strings
 * @return the concatenated string
 */
 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__)
 /**
 * Concatenates two or more strings using a UcxAllocator.
 *
 * @param ...     all remaining strings
 * @return the concatenated string
 */
 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.
 *
 * <b>Attention:</b> the new string references the same memory area as the
 * @see sstrsubs()
 * @see sstrchr()
 */
 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.
+*
+* <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);
+/**
+* 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);
-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.
 *
 *
 * @see sstrsubs()
 */
 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);
+/**
+* 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);
-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.
 *
 * @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>
 */
 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))
 /**
 * Splits a string into parts by using a delimiter string.
 *
 * @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
+* <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(string, delim, count) \
+ucx_strsplit(SCSTR(string), SCSTR(delim), count)
-#define sstrsplit(s, delim, count) ucx_strsplit(SCSTR(s), SCSTR(delim), count)
 /**
 * Performing sstrsplit() using a UcxAllocator.
 *
 * <i>Read the description of sstrsplit() for details.</i>
 * @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
+* <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
 * @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)
 */
 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))
 /**
 * Compares two UCX strings ignoring the case.
 *
 * the case.
 *
 * @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
+* length of s1 is greater than the length of s2 or the result of the platform
-* first two differing characters otherwise (i.e. 0 if the strings match and
+* specific string comparison function ignoring the case.
-* no characters differ)
 */
 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))
 /**
 * Creates a duplicate of the specified string.
 *
 * The new sstr_t will contain a copy allocated by standard
 * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
 * <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(string) ucx_strdup(SCSTR(string))
-#define sstrdup(s) scstrdup(SCSTR(s))
 /**
 * Creates a duplicate of the specified string using a UcxAllocator.
 *
 * The new sstr_t will contain a copy allocated by the allocators
 * ucx_allocator_malloc function. So it is implementation depended, whether the
 * returned sstr_t.ptr pointer must be passed to the allocators
 * 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.
+*
-size_t ucx_strtrim(const char *str, size_t length, size_t *newlen);
+* @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))
 /**
 * Omits leading and trailing spaces.
 *
 * This function returns a new sstr_t containing a trimmed version of the
 * @param string the string that shall be trimmed
 * @return a new sstr_t containing the trimmed string
 */
 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);
 /**
 * Checks, if a string has a specific prefix.
 * @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
 */
 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))
 /**
 * Checks, if a string has a specific suffix.
 * @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
 */
 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
 }
 #endif

Mercurial > hg > ucx / file comparison

comparison: src/ucx/string.h

src/ucx/string.h