1.1 --- a/src/ucx/string.h Wed May 16 13:13:33 2018 +0200
1.2 +++ b/src/ucx/string.h Wed May 16 14:02:59 2018 +0200
1.3 @@ -255,19 +255,26 @@
1.4
1.5 /**
1.6 * Returns the cumulated length of all specified strings.
1.7 - *
1.8 - * At least one string must be specified.
1.9 + *
1.10 + * You may arbitrarily mix up mutable (<code>sstr_t</code>) and immutable
1.11 + * (<code>scstr_t</code>) strings.
1.12 *
1.13 * <b>Attention:</b> if the count argument does not match the count of the
1.14 * specified strings, the behavior is undefined.
1.15 *
1.16 * @param count the total number of specified strings (so at least 1)
1.17 - * @param string the first string
1.18 - * @param ... all other strings
1.19 + * @param ... all strings
1.20 * @return the cumulated length of all strings
1.21 */
1.22 size_t ucx_strnlen(size_t count, ...);
1.23
1.24 +/**
1.25 + * Alias for ucx_strnlen().
1.26 + *
1.27 + * @param count the total number of specified strings (so at least 1)
1.28 + * @param ... all strings
1.29 + * @return the cumulated length of all strings
1.30 + */
1.31 #define sstrnlen(count, ...) ucx_strnlen(count, __VA_ARGS__)
1.32
1.33 /**
1.34 @@ -286,6 +293,14 @@
1.35 */
1.36 sstr_t ucx_strcat(size_t count, scstr_t s1, ...);
1.37
1.38 +/**
1.39 + * Alias for ucx_strcat() which automatically casts the first string.
1.40 + *
1.41 + * @param count the total number of strings to concatenate
1.42 + * @param s1 first string
1.43 + * @param ... all remaining strings
1.44 + * @return the concatenated string
1.45 + */
1.46 #define sstrcat(count, s1, ...) ucx_strcat(count, SCSTR(s1), __VA_ARGS__)
1.47
1.48 /**
1.49 @@ -301,7 +316,19 @@
1.50 */
1.51 sstr_t ucx_strcat_a(UcxAllocator *a, size_t count, scstr_t s1, ...);
1.52
1.53 -#define sstrcat_a(count, s1, ...) ucx_strcat_a(count, SCSTR(s1), __VA_ARGS__)
1.54 +/**
1.55 + * Alias for ucx_strcat_a() which automatically casts the first string.
1.56 + *
1.57 + * See sstrcat() for details.
1.58 + *
1.59 + * @param a the allocator to use
1.60 + * @param count the total number of strings to concatenate
1.61 + * @param s1 first string
1.62 + * @param ... all remaining strings
1.63 + * @return the concatenated string
1.64 + */
1.65 +#define sstrcat_a(a, count, s1, ...) \
1.66 + ucx_strcat_a(a, count, SCSTR(s1), __VA_ARGS__)
1.67
1.68 /**
1.69 * Returns a substring starting at the specified location.
1.70 @@ -337,13 +364,42 @@
1.71 */
1.72 sstr_t sstrsubsl(sstr_t string, size_t start, size_t length);
1.73
1.74 -scstr_t scstrsubs(scstr_t s, size_t start);
1.75 +/**
1.76 + * Returns a substring of an immutable string starting at the specified
1.77 + * location.
1.78 + *
1.79 + * <b>Attention:</b> the new string references the same memory area as the
1.80 + * input string and will <b>NOT</b> be <code>NULL</code>-terminated.
1.81 + * Use scstrdup() to get a copy.
1.82 + *
1.83 + * @param string input string
1.84 + * @param start start location of the substring
1.85 + * @return a substring of <code>string</code> starting at <code>start</code>
1.86 + *
1.87 + * @see scstrsubsl()
1.88 + * @see scstrchr()
1.89 + */
1.90 +scstr_t scstrsubs(scstr_t string, size_t start);
1.91 +
1.92 +/**
1.93 + * Returns a substring of an immutable string with a maximum length starting
1.94 + * at the specified location.
1.95 + *
1.96 + * <b>Attention:</b> the new string references the same memory area as the
1.97 + * input string and will <b>NOT</b> be <code>NULL</code>-terminated.
1.98 + * Use scstrdup() to get a copy.
1.99 + *
1.100 + * @param string input string
1.101 + * @param start start location of the substring
1.102 + * @param length the maximum length of the substring
1.103 + * @return a substring of <code>string</code> starting at <code>start</code>
1.104 + * with a maximum length of <code>length</code>
1.105 + *
1.106 + * @see scstrsubs()
1.107 + * @see scstrchr()
1.108 + */
1.109 scstr_t scstrsubsl(scstr_t string, size_t start, size_t length);
1.110
1.111 -
1.112 -int ucx_strchr(const char *string, size_t length, int chr, size_t *pos);
1.113 -int ucx_strrchr(const char *string, size_t length, int chr, size_t *pos);
1.114 -
1.115 /**
1.116 * Returns a substring starting at the location of the first occurrence of the
1.117 * specified character.
1.118 @@ -372,17 +428,34 @@
1.119 */
1.120 sstr_t sstrrchr(sstr_t string, int chr);
1.121
1.122 +/**
1.123 + * Returns an immutable substring starting at the location of the first
1.124 + * occurrence of the specified character.
1.125 + *
1.126 + * If the string does not contain the character, an empty string is returned.
1.127 + *
1.128 + * @param string the string where to locate the character
1.129 + * @param chr the character to locate
1.130 + * @return a substring starting at the first location of <code>chr</code>
1.131 + *
1.132 + * @see scstrsubs()
1.133 + */
1.134 +scstr_t scstrchr(scstr_t string, int chr);
1.135
1.136 -scstr_t scstrchr(scstr_t string, int chr);
1.137 +/**
1.138 + * Returns an immutable substring starting at the location of the last
1.139 + * occurrence of the specified character.
1.140 + *
1.141 + * If the string does not contain the character, an empty string is returned.
1.142 + *
1.143 + * @param string the string where to locate the character
1.144 + * @param chr the character to locate
1.145 + * @return a substring starting at the last location of <code>chr</code>
1.146 + *
1.147 + * @see scstrsubs()
1.148 + */
1.149 scstr_t scstrrchr(scstr_t string, int chr);
1.150
1.151 -const char* ucx_strstr(
1.152 - const char *str,
1.153 - size_t length,
1.154 - const char *match,
1.155 - size_t matchlen,
1.156 - size_t *newlen);
1.157 -
1.158 /**
1.159 * Returns a substring starting at the location of the first occurrence of the
1.160 * specified string.
1.161 @@ -399,9 +472,44 @@
1.162 * present in <code>string</code>
1.163 */
1.164 sstr_t ucx_sstrstr(sstr_t string, scstr_t match);
1.165 +
1.166 +/**
1.167 + * Alias for ucx_sstrstr() which automatically casts the match string.
1.168 + *
1.169 + * @param string the string to be scanned
1.170 + * @param match string containing the sequence of characters to match
1.171 + * @return a substring starting at the first occurrence of
1.172 + * <code>match</code>, or an empty string, if the sequence is not
1.173 + * present in <code>string</code>
1.174 + */
1.175 #define sstrstr(string, match) ucx_sstrstr(string, SCSTR(match))
1.176
1.177 +/**
1.178 + * Returns an immutable substring starting at the location of the
1.179 + * first occurrence of the specified immutable string.
1.180 + *
1.181 + * If the string does not contain the other string, an empty string is returned.
1.182 + *
1.183 + * If <code>match</code> is an empty string, the complete <code>string</code> is
1.184 + * returned.
1.185 + *
1.186 + * @param string the string to be scanned
1.187 + * @param match string containing the sequence of characters to match
1.188 + * @return a substring starting at the first occurrence of
1.189 + * <code>match</code>, or an empty string, if the sequence is not
1.190 + * present in <code>string</code>
1.191 + */
1.192 scstr_t ucx_scstrstr(scstr_t string, scstr_t match);
1.193 +
1.194 +/**
1.195 + * Alias for ucx_scstrstr() which automatically casts the match string.
1.196 + *
1.197 + * @param string the string to be scanned
1.198 + * @param match string containing the sequence of characters to match
1.199 + * @return a substring starting at the first occurrence of
1.200 + * <code>match</code>, or an empty string, if the sequence is not
1.201 + * present in <code>string</code>
1.202 + */
1.203 #define scstrstr(string, match) ucx_scstrstr(string, SCSTR(match))
1.204
1.205 /**
1.206 @@ -447,13 +555,26 @@
1.207 * @param count IN: the maximum size of the resulting array (0 = no limit),
1.208 * OUT: the actual size of the array
1.209 * @return a sstr_t array containing the split strings or
1.210 - * <code>NULL</code> on error
1.211 + * <code>NULL</code> on error
1.212 + *
1.213 + * @see ucx_strsplit_a()
1.214 + */
1.215 +sstr_t* ucx_strsplit(scstr_t string, scstr_t delim, ssize_t *count);
1.216 +
1.217 +/**
1.218 + * Alias for ucx_strsplit() which automatically casts the arguments.
1.219 + *
1.220 + * @param string the string to split
1.221 + * @param delim the delimiter string
1.222 + * @param count IN: the maximum size of the resulting array (0 = no limit),
1.223 + * OUT: the actual size of the array
1.224 + * @return a sstr_t array containing the split strings or
1.225 + * <code>NULL</code> on error
1.226 *
1.227 * @see sstrsplit_a()
1.228 */
1.229 -sstr_t* ucx_strsplit(scstr_t string, scstr_t delim, ssize_t *count);
1.230 -
1.231 -#define sstrsplit(s, delim, count) ucx_strsplit(SCSTR(s), SCSTR(delim), count)
1.232 +#define sstrsplit(string, delim, count) \
1.233 + ucx_strsplit(SCSTR(string), SCSTR(delim), count)
1.234
1.235 /**
1.236 * Performing sstrsplit() using a UcxAllocator.
1.237 @@ -473,19 +594,33 @@
1.238 * @param count IN: the maximum size of the resulting array (0 = no limit),
1.239 * OUT: the actual size of the array
1.240 * @return a sstr_t array containing the split strings or
1.241 - * <code>NULL</code> on error
1.242 + * <code>NULL</code> on error
1.243 *
1.244 - * @see sstrsplit()
1.245 + * @see ucx_strsplit()
1.246 */
1.247 sstr_t* ucx_strsplit_a(UcxAllocator *allocator, scstr_t string, scstr_t delim,
1.248 ssize_t *count);
1.249
1.250 -#define sstrsplit_a(a, s, d, c) ucx_strsplit_a(a, SCSTR(s), SCSTR(d, c))
1.251 +/**
1.252 + * Alias for ucx_strsplit_a() which automatically casts the arguments.
1.253 + *
1.254 + * @param allocator the UcxAllocator used for allocating memory
1.255 + * @param string the string to split
1.256 + * @param delim the delimiter string
1.257 + * @param count IN: the maximum size of the resulting array (0 = no limit),
1.258 + * OUT: the actual size of the array
1.259 + * @return a sstr_t array containing the split strings or
1.260 + * <code>NULL</code> on error
1.261 + *
1.262 + * @see sstrsplit()
1.263 + */
1.264 +#define sstrsplit_a(allocator, string, delim, count) \
1.265 + ucx_strsplit_a(allocator, SCSTR(string), SCSTR(delim, count))
1.266
1.267 /**
1.268 * Compares two UCX strings with standard <code>memcmp()</code>.
1.269 *
1.270 - * At first it compares the sstr_t.length attribute of the two strings. The
1.271 + * At first it compares the scstr_t.length attribute of the two strings. The
1.272 * <code>memcmp()</code> function is called, if and only if the lengths match.
1.273 *
1.274 * @param s1 the first string
1.275 @@ -496,6 +631,15 @@
1.276 */
1.277 int ucx_strcmp(scstr_t s1, scstr_t s2);
1.278
1.279 +/**
1.280 + * Alias for ucx_strcmp() which automatically casts its arguments.
1.281 + *
1.282 + * @param s1 the first string
1.283 + * @param s2 the second string
1.284 + * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.285 + * length of s1 is greater than the length of s2 or the result of
1.286 + * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
1.287 + */
1.288 #define sstrcmp(s1, s2) ucx_strcmp(SCSTR(s1), SCSTR(s2))
1.289
1.290 /**
1.291 @@ -508,12 +652,20 @@
1.292 * @param s1 the first string
1.293 * @param s2 the second string
1.294 * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.295 - * length of s1 is greater than the length of s2 or the difference between the
1.296 - * first two differing characters otherwise (i.e. 0 if the strings match and
1.297 - * no characters differ)
1.298 + * length of s1 is greater than the length of s2 or the result of the platform
1.299 + * specific string comparison function ignoring the case.
1.300 */
1.301 int ucx_strcasecmp(scstr_t s1, scstr_t s2);
1.302
1.303 +/**
1.304 + * Alias for ucx_strcasecmp() which automatically casts the arguments.
1.305 + *
1.306 + * @param s1 the first string
1.307 + * @param s2 the second string
1.308 + * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.309 + * length of s1 is greater than the length of s2 or the result of the platform
1.310 + * specific string comparison function ignoring the case.
1.311 + */
1.312 #define sstrcasecmp(s1, s2) ucx_strcasecmp(SCSTR(s1), SCSTR(s2))
1.313
1.314 /**
1.315 @@ -524,15 +676,22 @@
1.316 * <code>free()</code>.
1.317 *
1.318 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.319 - * terminated and mutable.
1.320 + * terminated and mutable, regardless of the argument.
1.321 + *
1.322 + * @param string the string to duplicate
1.323 + * @return a duplicate of the string
1.324 + * @see ucx_strdup_a()
1.325 + */
1.326 +sstr_t ucx_strdup(scstr_t string);
1.327 +
1.328 +/**
1.329 + * Alias for ucx_strdup() which automatically casts the argument.
1.330 *
1.331 * @param string the string to duplicate
1.332 * @return a duplicate of the string
1.333 * @see sstrdup_a()
1.334 */
1.335 -sstr_t scstrdup(scstr_t string);
1.336 -
1.337 -#define sstrdup(s) scstrdup(SCSTR(s))
1.338 +#define sstrdup(string) ucx_strdup(SCSTR(string))
1.339
1.340 /**
1.341 * Creates a duplicate of the specified string using a UcxAllocator.
1.342 @@ -543,20 +702,26 @@
1.343 * ucx_allocator_free function manually.
1.344 *
1.345 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.346 - * terminated.
1.347 + * terminated and mutable, regardless of the argument.
1.348 *
1.349 * @param allocator a valid instance of a UcxAllocator
1.350 * @param string the string to duplicate
1.351 * @return a duplicate of the string
1.352 - * @see sstrdup()
1.353 + * @see ucx_strdup()
1.354 */
1.355 -sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t string);
1.356 +sstr_t ucx_strdup_a(UcxAllocator *allocator, scstr_t string);
1.357
1.358 -#define sstrdup_a(allocator, s) scstrdup_a(allocator, SCSTR(s))
1.359 +/**
1.360 + * Alias for ucx_strdup_a() which automatically casts the argument.
1.361 + *
1.362 + * @param allocator a valid instance of a UcxAllocator
1.363 + * @param string the string to duplicate
1.364 + * @return a duplicate of the string
1.365 + * @see ucx_strdup()
1.366 + */
1.367 +#define sstrdup_a(allocator, string) ucx_strdup_a(allocator, SCSTR(string))
1.368
1.369
1.370 -size_t ucx_strtrim(const char *str, size_t length, size_t *newlen);
1.371 -
1.372 /**
1.373 * Omits leading and trailing spaces.
1.374 *
1.375 @@ -576,6 +741,23 @@
1.376 */
1.377 sstr_t sstrtrim(sstr_t string);
1.378
1.379 +/**
1.380 + * Omits leading and trailing spaces.
1.381 + *
1.382 + * This function returns a new scstr_t containing a trimmed version of the
1.383 + * specified string.
1.384 + *
1.385 + * <b>Note:</b> the new scstr_t references the same memory, thus you
1.386 + * <b>MUST NOT</b> pass the scstr_t.ptr of the return value to
1.387 + * <code>free()</code>. It is also highly recommended to avoid assignments like
1.388 + * <code>mystr = scstrtrim(mystr);</code> as you lose the reference to the
1.389 + * source string. Assignments of this type are only permitted, if the
1.390 + * scstr_t.ptr of the source string does not need to be freed or if another
1.391 + * reference to the source string exists.
1.392 + *
1.393 + * @param string the string that shall be trimmed
1.394 + * @return a new scstr_t containing the trimmed string
1.395 + */
1.396 scstr_t scstrtrim(scstr_t string);
1.397
1.398 /**
1.399 @@ -586,6 +768,13 @@
1.400 */
1.401 int ucx_strprefix(scstr_t string, scstr_t prefix);
1.402
1.403 +/**
1.404 + * Alias for ucx_strprefix() which automatically casts the arguments.
1.405 + *
1.406 + * @param string the string to check
1.407 + * @param prefix the prefix the string should have
1.408 + * @return 1, if and only if the string has the specified prefix, 0 otherwise
1.409 + */
1.410 #define sstrprefix(string, prefix) ucx_strprefix(SCSTR(string), SCSTR(prefix))
1.411
1.412 /**
1.413 @@ -596,64 +785,98 @@
1.414 */
1.415 int ucx_strsuffix(scstr_t string, scstr_t suffix);
1.416
1.417 -#define sstrsuffix(string, prefix) ucx_strsuffix(SCSTR(string), SCSTR(prefix))
1.418 +/**
1.419 + * Alias for ucx_strsuffix() which automatically casts the arguments.
1.420 + *
1.421 + * @param string the string to check
1.422 + * @param suffix the suffix the string should have
1.423 + * @return 1, if and only if the string has the specified suffix, 0 otherwise
1.424 + */
1.425 +#define sstrsuffix(string, suffix) ucx_strsuffix(SCSTR(string), SCSTR(suffix))
1.426
1.427 /**
1.428 * Returns a lower case version of a string.
1.429 *
1.430 * This function creates a duplicate of the input string, first. See the
1.431 - * documentation of sstrdup() for the implications.
1.432 + * documentation of scstrdup() for the implications.
1.433 *
1.434 * @param string the input string
1.435 * @return the resulting lower case string
1.436 - * @see sstrdup()
1.437 + * @see scstrdup()
1.438 */
1.439 sstr_t ucx_strlower(scstr_t string);
1.440
1.441 +/**
1.442 + * Alias for ucx_strlower() which automatically casts the argument.
1.443 + *
1.444 + * @param string the input string
1.445 + * @return the resulting lower case string
1.446 + */
1.447 #define sstrlower(string) ucx_strlower(SCSTR(string))
1.448
1.449 /**
1.450 * Returns a lower case version of a string.
1.451 *
1.452 * This function creates a duplicate of the input string, first. See the
1.453 - * documentation of sstrdup_a() for the implications.
1.454 + * documentation of scstrdup_a() for the implications.
1.455 *
1.456 * @param allocator the allocator used for duplicating the string
1.457 * @param string the input string
1.458 * @return the resulting lower case string
1.459 - * @see sstrdup_a()
1.460 + * @see scstrdup_a()
1.461 */
1.462 sstr_t ucx_strlower_a(UcxAllocator *allocator, scstr_t string);
1.463
1.464 +
1.465 +/**
1.466 + * Alias for ucx_strlower_a() which automatically casts the argument.
1.467 + *
1.468 + * @param allocator the allocator used for duplicating the string
1.469 + * @param string the input string
1.470 + * @return the resulting lower case string
1.471 + */
1.472 #define sstrlower_a(allocator, string) ucx_strlower_a(allocator, SCSTR(string))
1.473
1.474 /**
1.475 * Returns a upper case version of a string.
1.476 *
1.477 * This function creates a duplicate of the input string, first. See the
1.478 - * documentation of sstrdup() for the implications.
1.479 + * documentation of scstrdup() for the implications.
1.480 *
1.481 * @param string the input string
1.482 * @return the resulting upper case string
1.483 - * @see sstrdup()
1.484 + * @see scstrdup()
1.485 */
1.486 sstr_t ucx_strupper(scstr_t string);
1.487
1.488 +/**
1.489 + * Alias for ucx_strupper() which automatically casts the argument.
1.490 + *
1.491 + * @param string the input string
1.492 + * @return the resulting upper case string
1.493 + */
1.494 #define sstrupper(string) ucx_strupper(SCSTR(string))
1.495
1.496 /**
1.497 * Returns a upper case version of a string.
1.498 *
1.499 * This function creates a duplicate of the input string, first. See the
1.500 - * documentation of sstrdup_a() for the implications.
1.501 + * documentation of scstrdup_a() for the implications.
1.502 *
1.503 * @param allocator the allocator used for duplicating the string
1.504 * @param string the input string
1.505 * @return the resulting upper case string
1.506 - * @see sstrdup_a()
1.507 + * @see scstrdup_a()
1.508 */
1.509 sstr_t ucx_strupper_a(UcxAllocator *allocator, scstr_t string);
1.510
1.511 +/**
1.512 + * Alias for ucx_strupper_a() which automatically casts the argument.
1.513 + *
1.514 + * @param allocator the allocator used for duplicating the string
1.515 + * @param string the input string
1.516 + * @return the resulting upper case string
1.517 + */
1.518 #define sstrupper_a(allocator, string) ucx_strupper_a(allocator, string)
1.519
1.520 #ifdef __cplusplus
