--- a/ucx/string.h Tue Feb 16 17:39:33 2016 +0100
+++ b/ucx/string.h Mon May 23 12:28:32 2016 +0200
@@ -1,7 +1,7 @@
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
- * Copyright 2013 Olaf Wintermann. All rights reserved.
+ * Copyright 2015 Olaf Wintermann. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
@@ -119,38 +119,36 @@
*/
size_t sstrnlen(size_t count, sstr_t string, ...);
+/**
+ * Concatenates two or more strings.
+ *
+ * The resulting string will be 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.
+ *
+ * @param count the total number of strings to concatenate
+ * @param s1 first string
+ * @param s2 second string
+ * @param ... all remaining strings
+ * @return the concatenated string
+ */
+sstr_t sstrcat(size_t count, sstr_t s1, sstr_t s2, ...);
/**
- * Concatenates strings.
- *
- * At least one string must be specified and there must be enough memory
- * available referenced by the destination sstr_t.ptr for this function to
- * successfully concatenate all specified strings.
- *
- * The sstr_t.length of the destination string specifies the capacity and
- * should match the total memory available referenced by the destination
- * sstr_t.ptr. This function <i>never</i> copies data beyond the capacity and
- * does not modify any of the source strings.
+ * Concatenates two or more strings using an UcxAllocator.
*
- * <b>Attention:</b>
- * <ul>
- * <li>Any content in the destination string will be overwritten</li>
- * <li>The destination sstr_t.ptr is <b>NOT</b>
- * <code>NULL</code>-terminated</li>
- * <li>The destination sstr_t.length is set to the total length of the
- * concatenated strings</li>
- * <li><i>Hint:</i> get a <code>NULL</code>-terminated string by performing
- * <code>mystring.ptr[mystring.length]='\0'</code> after calling this
- * function</li>
- * </ul>
+ * See sstrcat() for details.
*
- * @param dest new sstr_t with capacity information and allocated memory
+ * @param a the allocator to use
* @param count the total number of strings to concatenate
- * @param src the first string
- * @param ... all other strings
- * @return the argument for <code>dest</code> is returned
+ * @param s1 first string
+ * @param s2 second string
+ * @param ... all remaining strings
+ * @return the concatenated string
*/
-sstr_t sstrncat(sstr_t dest, size_t count, sstr_t src, ...);
+sstr_t sstrcat_a(UcxAllocator *a, size_t count, sstr_t s1, sstr_t s2, ...);
/**
@@ -227,7 +225,7 @@
* </ul>
*
* The integer referenced by <code>count</code> is used as input and determines
- * the maximum size of the resulting list, i.e. the maximum count of splits to
+ * the maximum size of the resulting array, i.e. the maximum count of splits to
* perform + 1.
*
* The integer referenced by <code>count</code> is also used as output and is
@@ -237,36 +235,36 @@
* <li>-1, if either the string or the delimiter is an empty string</li>
* <li>0, if the string equals the delimiter</li>
* <li>1, if the string does not contain the delimiter</li>
- * <li>the count of list items, otherwise</li>
+ * <li>the count of array items, otherwise</li>
* </ul>
*
* If the string starts with the delimiter, the first item of the resulting
- * list will be an empty string.
+ * array will be an empty string.
*
* If the string ends with the delimiter and the maximum list size is not
- * exceeded, the last list item will be an empty string.
+ * exceeded, the last array item will be an empty string.
*
- * <b>Attention:</b> All list items <b>AND</b> all sstr_t.ptr of the list
+ * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array
* items must be manually passed to <code>free()</code>. Use sstrsplit_a() with
* an allocator to managed memory, to avoid this.
*
* @param string the string to split
* @param delim the delimiter string
- * @param count IN: the maximum size of the resulting list (0 for an
- * unbounded list), OUT: the actual size of the list
- * @return a list of the split strings as sstr_t array or
+ * @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* sstrsplit(sstr_t string, sstr_t delim, size_t *count);
+sstr_t* sstrsplit(sstr_t string, sstr_t delim, ssize_t *count);
/**
* Performing sstrsplit() using an UcxAllocator.
*
* <i>Read the description of sstrsplit() for details.</i>
*
- * The memory for the sstr_t.ptr pointers of the list items and the memory for
+ * The memory for the sstr_t.ptr pointers of the array items and the memory for
* the sstr_t array itself are allocated by using the UcxAllocator.malloc()
* function.
*
@@ -276,15 +274,15 @@
* @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 list (0 for an
- * unbounded list), OUT: the actual size of the list
- * @return a list of the split strings as sstr_t array or
+ * @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()
*/
sstr_t* sstrsplit_a(UcxAllocator *allocator, sstr_t string, sstr_t delim,
- size_t *count);
+ ssize_t *count);
/**
* Compares two UCX strings with standard <code>memcmp()</code>.
@@ -385,6 +383,56 @@
*/
int sstrsuffix(sstr_t string, sstr_t 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.
+ *
+ * @param string the input string
+ * @return the resulting lower case string
+ * @see sstrdup()
+ */
+sstr_t sstrlower(sstr_t 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.
+ *
+ * @param allocator the allocator used for duplicating the string
+ * @param string the input string
+ * @return the resulting lower case string
+ * @see sstrdup_a()
+ */
+sstr_t sstrlower_a(UcxAllocator *allocator, sstr_t 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.
+ *
+ * @param string the input string
+ * @return the resulting upper case string
+ * @see sstrdup()
+ */
+sstr_t sstrupper(sstr_t 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.
+ *
+ * @param allocator the allocator used for duplicating the string
+ * @param string the input string
+ * @return the resulting upper case string
+ * @see sstrdup_a()
+ */
+sstr_t sstrupper_a(UcxAllocator *allocator, sstr_t string);
+
#ifdef __cplusplus
}
#endif
