1.1 --- a/ucx/string.h Wed Jul 17 20:03:01 2013 +0200
1.2 +++ b/ucx/string.h Fri Jul 19 14:17:12 2013 +0200
1.3 @@ -119,48 +119,157 @@
1.4 size_t sstrnlen(size_t count, sstr_t string, ...);
1.5
1.6
1.7 -/*
1.8 - * concatenates n strings
1.9 +/**
1.10 + * Concatenates strings.
1.11 + *
1.12 + * At least one string must be specified and there must be enough memory
1.13 + * available referenced by the destination sstr_t.ptr for this function to
1.14 + * successfully concatenate all specified strings.
1.15 + *
1.16 + * The sstr_t.length of the destination string specifies the capacity and
1.17 + * should match the total memory available referenced by the destination
1.18 + * sstr_t.ptr. This function <i>never</i> copies data beyond the capacity and
1.19 + * does not modify any of the source strings.
1.20 + *
1.21 + * <b>Attention:</b>
1.22 + * <ul>
1.23 + * <li>Any content in the destination string will be overwritten</li>
1.24 + * <li>The destination sstr_t.ptr is <b>NOT</b>
1.25 + * <code>NULL</code>-terminated</li>
1.26 + * <li>The destination sstr_t.length is set to the total length of the
1.27 + * concatenated strings</li>
1.28 + * <li><i>Hint:</i> get a <code>NULL</code>-terminated string by performing
1.29 + * <code>mystring.ptr[mystring.length]='\0'</code> after calling this
1.30 + * function</li>
1.31 + * </ul>
1.32 + *
1.33 + * @param count the total number of strings to concatenate
1.34 + * @param dest new sstr_t with capacity information and allocated memory
1.35 + * @param src the first string
1.36 + * @param ... all other strings
1.37 + * @return the argument for <code>dest</code> is returned
1.38 + */
1.39 +sstr_t sstrncat(size_t count, sstr_t dest, sstr_t src, ...);
1.40 +
1.41 +
1.42 +/**
1.43 + * Returns a substring starting at the specified location.
1.44 + *
1.45 + * <b>Attention:</b> the new string references the same memory area as the
1.46 + * input string and will <b>NOT</b> be <code>NULL</code>-terminated.
1.47 + * Use sstrdup() to get a copy.
1.48 + *
1.49 + * @param string input string
1.50 + * @param start start location of the substring
1.51 + * @return a substring of <code>string</code> starting at <code>start</code>
1.52 + *
1.53 + * @see sstrsubsl()
1.54 + * @see sstrchr()
1.55 + */
1.56 +sstr_t sstrsubs(sstr_t string, size_t start);
1.57 +
1.58 +/**
1.59 + * Returns a substring with a maximum length starting at the specified location.
1.60 + *
1.61 + * <b>Attention:</b> the new string references the same memory area as the
1.62 + * input string and will <b>NOT</b> be <code>NULL</code>-terminated.
1.63 + * Use sstrdup() to get a copy.
1.64 + *
1.65 + * @param string input string
1.66 + * @param start start location of the substring
1.67 + * @param length the maximum length of the substring
1.68 + * @return a substring of <code>string</code> starting at <code>start</code>
1.69 + * with a maximum length of <code>length</code>
1.70 + *
1.71 + * @see sstrsubs()
1.72 + * @see sstrchr()
1.73 + */
1.74 +sstr_t sstrsubsl(sstr_t string, size_t start, size_t length);
1.75 +
1.76 +/**
1.77 + * Returns a substring starting at the location of the first occurrence of the
1.78 + * specified character.
1.79 + *
1.80 + * If the string does not contain the character, an empty string is returned.
1.81 + *
1.82 + * @param string the string where to locate the character
1.83 + * @param chr the character to locate
1.84 + * @return a substring starting at the least location of <code>chr</code>
1.85 + *
1.86 + * @see sstrsubs()
1.87 + */
1.88 +sstr_t sstrchr(sstr_t string, int chr);
1.89 +
1.90 +/**
1.91 + * Splits a string into parts by using a delimiter string.
1.92 + *
1.93 + * This function will return <code>NULL</code>, if one of the following happens:
1.94 + * <ul>
1.95 + * <li>the string length is zero</li>
1.96 + * <li>the delimeter length is zero</li>
1.97 + * <li>the string equals the delimeter</li>
1.98 + * <li>memory allocation fails</li>
1.99 + * </ul>
1.100 + *
1.101 + * The integer referenced by <code>count</code> is used as input and determines
1.102 + * the maximum size of the resulting list, i.e. the maximum count of splits to
1.103 + * perform + 1.
1.104 + *
1.105 + * The integer referenced by <code>count</code> is also used as output and is
1.106 + * set to
1.107 + * <ul>
1.108 + * <li>-2, on memory allocation errors</li>
1.109 + * <li>-1, if either the string or the delimiter is an empty string</li>
1.110 + * <li>0, if the string equals the delimiter</li>
1.111 + * <li>1, if the string does not contain the delimiter</li>
1.112 + * <li>the count of list items, otherwise</li>
1.113 + * </ul>
1.114 + *
1.115 + * If the string starts with the delimiter, the first item of the resulting
1.116 + * list will be an empty string.
1.117 + *
1.118 + * If the string ends with the delimiter and the maximum list size is not
1.119 + * exceeded, the last list item will be an empty string.
1.120 + *
1.121 + * <b>Attention:</b> All list items <b>AND</b> all sstr_t.ptr of the list
1.122 + * items must be manually passed to <code>free()</code>. Use sstrsplita() with
1.123 + * an allocator to managed memory, to avoid this.
1.124 *
1.125 - * n number of strings
1.126 - * s new string with enough memory allocated
1.127 - * ... strings
1.128 + * @param string the string to split
1.129 + * @param delim the delimiter string
1.130 + * @param count IN: the maximum size of the resulting list (0 for an
1.131 + * unbounded list), OUT: the actual size of the list
1.132 + * @return a list of the split strings as sstr_t array or
1.133 + * <code>NULL</code> on error
1.134 + *
1.135 + * @see sstrsplita()
1.136 */
1.137 -sstr_t sstrncat(size_t n, sstr_t s, sstr_t c1, ...);
1.138 +sstr_t* sstrsplit(sstr_t string, sstr_t delim, size_t *count);
1.139
1.140 -
1.141 -/*
1.142 - *
1.143 +/**
1.144 + * Performing sstrsplit() using an UcxAllocator.
1.145 + *
1.146 + * <i>Read the description of sstrsplit() for details.</i>
1.147 + *
1.148 + * The memory for the sstr_t.ptr pointers of the list items and the memory for
1.149 + * the sstr_t array itself are allocated by using the UcxAllocator.malloc()
1.150 + * function.
1.151 + *
1.152 + * <b>Note:</b> the allocator is not used for memory that is freed within the
1.153 + * same call of this function (locally scoped variables).
1.154 + *
1.155 + * @param string the string to split
1.156 + * @param delim the delimiter string
1.157 + * @param count IN: the maximum size of the resulting list (0 for an
1.158 + * unbounded list), OUT: the actual size of the list
1.159 + * @param allocator the UcxAllocator used for allocating memory
1.160 + * @return a list of the split strings as sstr_t array or
1.161 + * <code>NULL</code> on error
1.162 + *
1.163 + * @see sstrsplit()
1.164 */
1.165 -sstr_t sstrsubs(sstr_t s, size_t start);
1.166 -
1.167 -/*
1.168 - *
1.169 - */
1.170 -sstr_t sstrsubsl(sstr_t s, size_t start, size_t length);
1.171 -
1.172 -/*
1.173 - *
1.174 - */
1.175 -sstr_t sstrchr(sstr_t s, int c);
1.176 -
1.177 -/*
1.178 - * splits s into n parts
1.179 - *
1.180 - * s the string to split
1.181 - * d the delimiter string
1.182 - * n the maximum size of the resulting list
1.183 - * a size of 0 indicates an unbounded list size
1.184 - * the actual size of the list will be stored here
1.185 - *
1.186 - * Hint: use this value to avoid dynamic reallocation of the result list
1.187 - *
1.188 - * Returns a list of the split strings
1.189 - * NOTE: this list needs to be freed manually after usage
1.190 - *
1.191 - * Returns NULL on error
1.192 - */
1.193 -sstr_t* sstrsplit(sstr_t s, sstr_t d, size_t *n);
1.194 +sstr_t* sstrsplita(sstr_t string, sstr_t delim, size_t *count,
1.195 + UcxAllocator *allocator);
1.196
1.197 /**
1.198 * Compares two UCX strings with standard <code>memcmp()</code>.
1.199 @@ -188,6 +297,7 @@
1.200 *
1.201 * @param string the string to duplicate
1.202 * @return a duplicate of the string
1.203 + * @see sstrdupa()
1.204 */
1.205 sstr_t sstrdup(sstr_t string);
1.206
1.207 @@ -205,6 +315,7 @@
1.208 * @param allocator a valid instance of an UcxAllocator
1.209 * @param string the string to duplicate
1.210 * @return a duplicate of the string
1.211 + * @see sstrdup()
1.212 */
1.213 sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string);
1.214
