362:39cef8f37eb5 | 363:8175ba2b3bcb |
---|---|
81 #endif /* UCX_NO_SSTR_FORMAT_MACROS */ | 81 #endif /* UCX_NO_SSTR_FORMAT_MACROS */ |
82 | 82 |
83 #ifdef __cplusplus | 83 #ifdef __cplusplus |
84 extern "C" { | 84 extern "C" { |
85 #endif | 85 #endif |
86 | |
86 /** | 87 /** |
87 * The UCX string structure. | 88 * The UCX string structure. |
88 */ | 89 */ |
89 typedef struct { | 90 typedef struct { |
90 /** A pointer to the string | 91 /** A pointer to the string |
110 #endif | 111 #endif |
111 | 112 |
112 | 113 |
113 #ifdef __cplusplus | 114 #ifdef __cplusplus |
114 /** | 115 /** |
115 * One of two type adjustment functions that return a scstr_t. | 116 * One of two type adjustment functions that return an scstr_t. |
116 * | 117 * |
117 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. | 118 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. |
118 * | 119 * |
119 * <b>Do not use this function manually.</b> | 120 * <b>Do not use this function manually.</b> |
120 * | 121 * |
127 c.length = s.length; | 128 c.length = s.length; |
128 return c; | 129 return c; |
129 } | 130 } |
130 | 131 |
131 /** | 132 /** |
132 * One of two type adjustment functions that return a scstr_t. | 133 * One of two type adjustment functions that return an scstr_t. |
133 * | 134 * |
134 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. | 135 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. |
135 * This variant is used, when the string is already immutable and no operation | 136 * This variant is used, when the string is already immutable and no operation |
136 * needs to be performed. | 137 * needs to be performed. |
137 * | 138 * |
145 } | 146 } |
146 | 147 |
147 /** | 148 /** |
148 * Converts a UCX string to an immutable UCX string (scstr_t). | 149 * Converts a UCX string to an immutable UCX string (scstr_t). |
149 * @param str some UCX string | 150 * @param str some UCX string |
150 * @return the an immutable version of the provided string | 151 * @return an immutable version of the provided string |
151 */ | 152 */ |
152 #define SCSTR(s) s2scstr(s) | 153 #define SCSTR(s) s2scstr(s) |
153 #else | 154 #else |
154 | 155 |
155 /** | 156 /** |
156 * One of two type adjustment functions that return a scstr_t. | 157 * One of two type adjustment functions that return an scstr_t. |
157 * | 158 * |
158 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. | 159 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. |
159 * This variant is used, when the string is already immutable and no operation | 160 * This variant is used, when the string is already immutable and no operation |
160 * needs to be performed. | 161 * needs to be performed. |
161 * | 162 * |
165 * @return the argument itself | 166 * @return the argument itself |
166 */ | 167 */ |
167 scstr_t ucx_sc2sc(scstr_t str); | 168 scstr_t ucx_sc2sc(scstr_t str); |
168 | 169 |
169 /** | 170 /** |
170 * One of two type adjustment functions that return a scstr_t. | 171 * One of two type adjustment functions that return an scstr_t. |
171 * | 172 * |
172 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. | 173 * Used <b>internally</b> to convert a UCX string to an immutable UCX string. |
173 * | 174 * |
174 * <b>Do not use this function manually.</b> | 175 * <b>Do not use this function manually.</b> |
175 * | 176 * |
180 | 181 |
181 #if __STDC_VERSION__ >= 201112L | 182 #if __STDC_VERSION__ >= 201112L |
182 /** | 183 /** |
183 * Converts a UCX string to an immutable UCX string (scstr_t). | 184 * Converts a UCX string to an immutable UCX string (scstr_t). |
184 * @param str some UCX string | 185 * @param str some UCX string |
185 * @return the an immutable version of the provided string | 186 * @return an immutable version of the provided string |
186 */ | 187 */ |
187 #define SCSTR(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str) | 188 #define SCSTR(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str) |
188 | 189 |
189 #elif defined(__GNUC__) || defined(__clang__) | 190 #elif defined(__GNUC__) || defined(__clang__) |
190 | 191 |
191 /** | 192 /** |
192 * Converts a UCX string to an immutable UCX string (scstr_t). | 193 * Converts a UCX string to an immutable UCX string (scstr_t). |
193 * @param str some UCX string | 194 * @param str some UCX string |
194 * @return the an immutable version of the provided string | 195 * @return an immutable version of the provided string |
195 */ | 196 */ |
196 #define SCSTR(str) __builtin_choose_expr( \ | 197 #define SCSTR(str) __builtin_choose_expr( \ |
197 __builtin_types_compatible_p(typeof(str), sstr_t), \ | 198 __builtin_types_compatible_p(typeof(str), sstr_t), \ |
198 ucx_ss2sc, \ | 199 ucx_ss2sc, \ |
199 ucx_sc2sc)(str) | 200 ucx_sc2sc)(str) |
242 /** | 243 /** |
243 * Creates a new sstr_t based on a C string. | 244 * Creates a new sstr_t based on a C string. |
244 * | 245 * |
245 * The length is implicitly inferred by using a call to <code>strlen()</code>. | 246 * The length is implicitly inferred by using a call to <code>strlen()</code>. |
246 * | 247 * |
247 * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you | 248 * <b>Note:</b> the sstr_t will share the specified pointer to the C string. |
248 * do want a copy, use sstrdup() on the return value of this function. | 249 * If you do want a copy, use sstrdup() on the return value of this function. |
249 * | 250 * |
250 * If you need to wrap a constant string, use scstr(). | 251 * If you need to wrap a constant string, use scstr(). |
251 * | 252 * |
252 * @param cstring the C string to wrap | 253 * @param cstring the C string to wrap |
253 * @return a new sstr_t containing the C string | 254 * @return a new sstr_t containing the C string |
257 sstr_t sstr(char *cstring); | 258 sstr_t sstr(char *cstring); |
258 | 259 |
259 /** | 260 /** |
260 * Creates a new sstr_t of the specified length based on a C string. | 261 * Creates a new sstr_t of the specified length based on a C string. |
261 * | 262 * |
262 * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you | 263 * <b>Note:</b> the sstr_t will share the specified pointer to the C string. |
263 * do want a copy, use sstrdup() on the return value of this function. | 264 * If you do want a copy, use sstrdup() on the return value of this function. |
264 * | 265 * |
265 * If you need to wrap a constant string, use scstrn(). | 266 * If you need to wrap a constant string, use scstrn(). |
266 * | 267 * |
267 * @param cstring the C string to wrap | 268 * @param cstring the C string to wrap |
268 * @param length the length of the string | 269 * @param length the length of the string |
276 /** | 277 /** |
277 * Creates a new scstr_t based on a constant C string. | 278 * Creates a new scstr_t based on a constant C string. |
278 * | 279 * |
279 * The length is implicitly inferred by using a call to <code>strlen()</code>. | 280 * The length is implicitly inferred by using a call to <code>strlen()</code>. |
280 * | 281 * |
281 * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you | 282 * <b>Note:</b> the scstr_t will share the specified pointer to the C string. |
282 * do want a copy, use scstrdup() on the return value of this function. | 283 * If you do want a copy, use scstrdup() on the return value of this function. |
283 * | 284 * |
284 * @param cstring the C string to wrap | 285 * @param cstring the C string to wrap |
285 * @return a new scstr_t containing the C string | 286 * @return a new scstr_t containing the C string |
286 * | 287 * |
287 * @see scstrn() | 288 * @see scstrn() |
290 | 291 |
291 | 292 |
292 /** | 293 /** |
293 * Creates a new scstr_t of the specified length based on a constant C string. | 294 * Creates a new scstr_t of the specified length based on a constant C string. |
294 * | 295 * |
295 * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you | 296 * <b>Note:</b> the scstr_t will share the specified pointer to the C string. |
296 * do want a copy, use scstrdup() on the return value of this function. | 297 * If you do want a copy, use scstrdup() on the return value of this function. * |
297 * | |
298 * | 298 * |
299 * @param cstring the C string to wrap | 299 * @param cstring the C string to wrap |
300 * @param length the length of the string | 300 * @param length the length of the string |
301 * @return a new scstr_t containing the C string | 301 * @return a new scstr_t containing the C string |
302 * | 302 * |
303 * @see scstr() | 303 * @see scstr() |
304 */ | 304 */ |
305 scstr_t scstrn(const char *cstring, size_t length); | 305 scstr_t scstrn(const char *cstring, size_t length); |
306 | 306 |
307 /** | 307 /** |
308 * Returns the cumulated length of all specified strings. | 308 * Returns the accumulated length of all specified strings. |
309 * | 309 * |
310 * <b>Attention:</b> if the count argument does not match the count of the | 310 * <b>Attention:</b> if the count argument is larger than the count of the |
311 * specified strings, the behavior is undefined. | 311 * specified strings, the behavior is undefined. |
312 * | 312 * |
313 * @param count the total number of specified strings (so at least 1) | 313 * @param count the total number of specified strings |
314 * @param ... all strings | 314 * @param ... all strings |
315 * @return the cumulated length of all strings | 315 * @return the accumulated length of all strings |
316 */ | 316 */ |
317 size_t scstrnlen(size_t count, ...); | 317 size_t scstrnlen(size_t count, ...); |
318 | 318 |
319 /** | 319 /** |
320 * Alias for scstrnlen() which automatically converts the arguments. | 320 * Returns the accumulated length of all specified strings. |
321 * | 321 * |
322 * @param count the total number of specified strings (so at least 1) | 322 * <b>Attention:</b> if the count argument is larger than the count of the |
323 * specified strings, the behavior is undefined. | |
324 * | |
325 * @param count the total number of specified strings | |
323 * @param ... all strings | 326 * @param ... all strings |
324 * @return the cumulated length of all strings | 327 * @return the cumulated length of all strings |
325 */ | 328 */ |
326 #define sstrnlen(count, ...) scstrnlen(count, __VA_ARGS__) | 329 #define sstrnlen(count, ...) scstrnlen(count, __VA_ARGS__) |
327 | 330 |
340 * @return the concatenated string | 343 * @return the concatenated string |
341 */ | 344 */ |
342 sstr_t scstrcat(size_t count, scstr_t s1, ...); | 345 sstr_t scstrcat(size_t count, scstr_t s1, ...); |
343 | 346 |
344 /** | 347 /** |
345 * Alias for scstrcat() which automatically converts the arguments. | 348 * Concatenates two or more strings. |
349 * | |
350 * The resulting string will be allocated by standard <code>malloc()</code>. | |
351 * So developers <b>MUST</b> pass the sstr_t.ptr to <code>free()</code>. | |
352 * | |
353 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>- | |
354 * terminated. | |
346 * | 355 * |
347 * @param count the total number of strings to concatenate | 356 * @param count the total number of strings to concatenate |
348 * @param s1 first string | 357 * @param s1 first string |
349 * @param ... all remaining strings | 358 * @param ... all remaining strings |
350 * @return the concatenated string | 359 * @return the concatenated string |
352 #define sstrcat(count, s1, ...) scstrcat(count, SCSTR(s1), __VA_ARGS__) | 361 #define sstrcat(count, s1, ...) scstrcat(count, SCSTR(s1), __VA_ARGS__) |
353 | 362 |
354 /** | 363 /** |
355 * Concatenates two or more strings using a UcxAllocator. | 364 * Concatenates two or more strings using a UcxAllocator. |
356 * | 365 * |
357 * See scstrcat() for details. | 366 * The resulting string must be freed by the allocators <code>free()</code> |
358 * | 367 * implementation. |
359 * @param a the allocator to use | 368 * |
369 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>- | |
370 * terminated. | |
371 * | |
372 * @param alloc the allocator to use | |
360 * @param count the total number of strings to concatenate | 373 * @param count the total number of strings to concatenate |
361 * @param s1 first string | 374 * @param s1 first string |
362 * @param ... all remaining strings | 375 * @param ... all remaining strings |
363 * @return the concatenated string | 376 * @return the concatenated string |
364 */ | 377 * |
365 sstr_t scstrcat_a(UcxAllocator *a, size_t count, scstr_t s1, ...); | 378 * @see scstrcat() |
366 | 379 */ |
367 /** | 380 sstr_t scstrcat_a(UcxAllocator *alloc, size_t count, scstr_t s1, ...); |
368 * Alias for scstrcat_a() which automatically converts the arguments. | 381 |
369 * | 382 /** |
370 * See sstrcat() for details. | 383 * Concatenates two or more strings using a UcxAllocator. |
371 * | 384 * |
372 * @param a the allocator to use | 385 * The resulting string must be freed by the allocators <code>free()</code> |
386 * implementation. | |
387 * | |
388 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>- | |
389 * terminated. | |
390 * | |
391 * @param alloc the allocator to use | |
373 * @param count the total number of strings to concatenate | 392 * @param count the total number of strings to concatenate |
374 * @param s1 first string | 393 * @param s1 first string |
375 * @param ... all remaining strings | 394 * @param ... all remaining strings |
376 * @return the concatenated string | 395 * @return the concatenated string |
377 */ | 396 * |
378 #define sstrcat_a(a, count, s1, ...) \ | 397 * @see sstrcat() |
379 scstrcat_a(a, count, SCSTR(s1), __VA_ARGS__) | 398 */ |
399 #define sstrcat_a(alloc, count, s1, ...) \ | |
400 scstrcat_a(alloc, count, SCSTR(s1), __VA_ARGS__) | |
380 | 401 |
381 /** | 402 /** |
382 * Returns a substring starting at the specified location. | 403 * Returns a substring starting at the specified location. |
383 * | 404 * |
384 * <b>Attention:</b> the new string references the same memory area as the | 405 * <b>Attention:</b> the new string references the same memory area as the |
385 * input string and will <b>NOT</b> be <code>NULL</code>-terminated. | 406 * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated. |
386 * Use sstrdup() to get a copy. | 407 * Use sstrdup() to get a copy. |
387 * | 408 * |
388 * @param string input string | 409 * @param string input string |
389 * @param start start location of the substring | 410 * @param start start location of the substring |
390 * @return a substring of <code>string</code> starting at <code>start</code> | 411 * @return a substring of <code>string</code> starting at <code>start</code> |
393 * @see sstrchr() | 414 * @see sstrchr() |
394 */ | 415 */ |
395 sstr_t sstrsubs(sstr_t string, size_t start); | 416 sstr_t sstrsubs(sstr_t string, size_t start); |
396 | 417 |
397 /** | 418 /** |
398 * Returns a substring with a maximum length starting at the specified location. | 419 * Returns a substring with the given length starting at the specified location. |
399 * | 420 * |
400 * <b>Attention:</b> the new string references the same memory area as the | 421 * <b>Attention:</b> the new string references the same memory area as the |
401 * input string and will <b>NOT</b> be <code>NULL</code>-terminated. | 422 * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated. |
402 * Use sstrdup() to get a copy. | 423 * Use sstrdup() to get a copy. |
403 * | 424 * |
404 * @param string input string | 425 * @param string input string |
405 * @param start start location of the substring | 426 * @param start start location of the substring |
406 * @param length the maximum length of the substring | 427 * @param length the maximum length of the substring |
415 /** | 436 /** |
416 * Returns a substring of an immutable string starting at the specified | 437 * Returns a substring of an immutable string starting at the specified |
417 * location. | 438 * location. |
418 * | 439 * |
419 * <b>Attention:</b> the new string references the same memory area as the | 440 * <b>Attention:</b> the new string references the same memory area as the |
420 * input string and will <b>NOT</b> be <code>NULL</code>-terminated. | 441 * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated. |
421 * Use scstrdup() to get a copy. | 442 * Use scstrdup() to get a copy. |
422 * | 443 * |
423 * @param string input string | 444 * @param string input string |
424 * @param start start location of the substring | 445 * @param start start location of the substring |
425 * @return a substring of <code>string</code> starting at <code>start</code> | 446 * @return a substring of <code>string</code> starting at <code>start</code> |
432 /** | 453 /** |
433 * Returns a substring of an immutable string with a maximum length starting | 454 * Returns a substring of an immutable string with a maximum length starting |
434 * at the specified location. | 455 * at the specified location. |
435 * | 456 * |
436 * <b>Attention:</b> the new string references the same memory area as the | 457 * <b>Attention:</b> the new string references the same memory area as the |
437 * input string and will <b>NOT</b> be <code>NULL</code>-terminated. | 458 * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated. |
438 * Use scstrdup() to get a copy. | 459 * Use scstrdup() to get a copy. |
439 * | 460 * |
440 * @param string input string | 461 * @param string input string |
441 * @param start start location of the substring | 462 * @param start start location of the substring |
442 * @param length the maximum length of the substring | 463 * @param length the maximum length of the substring |
520 * present in <code>string</code> | 541 * present in <code>string</code> |
521 */ | 542 */ |
522 sstr_t scstrsstr(sstr_t string, scstr_t match); | 543 sstr_t scstrsstr(sstr_t string, scstr_t match); |
523 | 544 |
524 /** | 545 /** |
525 * Alias for scstrsstr() which automatically converts the match string. | 546 * Returns a substring starting at the location of the first occurrence of the |
547 * specified string. | |
548 * | |
549 * If the string does not contain the other string, an empty string is returned. | |
550 * | |
551 * If <code>match</code> is an empty string, the complete <code>string</code> is | |
552 * returned. | |
526 * | 553 * |
527 * @param string the string to be scanned | 554 * @param string the string to be scanned |
528 * @param match string containing the sequence of characters to match | 555 * @param match string containing the sequence of characters to match |
529 * @return a substring starting at the first occurrence of | 556 * @return a substring starting at the first occurrence of |
530 * <code>match</code>, or an empty string, if the sequence is not | 557 * <code>match</code>, or an empty string, if the sequence is not |
548 * present in <code>string</code> | 575 * present in <code>string</code> |
549 */ | 576 */ |
550 scstr_t scstrscstr(scstr_t string, scstr_t match); | 577 scstr_t scstrscstr(scstr_t string, scstr_t match); |
551 | 578 |
552 /** | 579 /** |
553 * Alias for scstrscstr() which automatically converts the match string. | 580 * Returns an immutable substring starting at the location of the |
581 * first occurrence of the specified immutable string. | |
582 * | |
583 * If the string does not contain the other string, an empty string is returned. | |
584 * | |
585 * If <code>match</code> is an empty string, the complete <code>string</code> is | |
586 * returned. | |
554 * | 587 * |
555 * @param string the string to be scanned | 588 * @param string the string to be scanned |
556 * @param match string containing the sequence of characters to match | 589 * @param match string containing the sequence of characters to match |
557 * @return a substring starting at the first occurrence of | 590 * @return a substring starting at the first occurrence of |
558 * <code>match</code>, or an empty string, if the sequence is not | 591 * <code>match</code>, or an empty string, if the sequence is not |
593 * In case the list size would be exceeded, the last array item will be the | 626 * In case the list size would be exceeded, the last array item will be the |
594 * remaining string after the last split, <i>including</i> the terminating | 627 * remaining string after the last split, <i>including</i> the terminating |
595 * delimiter. | 628 * delimiter. |
596 * | 629 * |
597 * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array | 630 * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array |
598 * items must be manually passed to <code>free()</code>. Use sstrsplit_a() with | 631 * items must be manually passed to <code>free()</code>. Use scstrsplit_a() with |
599 * an allocator to managed memory, to avoid this. | 632 * an allocator to managed memory, to avoid this. |
600 * | 633 * |
601 * @param string the string to split | 634 * @param string the string to split |
602 * @param delim the delimiter string | 635 * @param delim the delimiter string |
603 * @param count IN: the maximum size of the resulting array (0 = no limit), | 636 * @param count IN: the maximum size of the resulting array (0 = no limit), |
608 * @see scstrsplit_a() | 641 * @see scstrsplit_a() |
609 */ | 642 */ |
610 sstr_t* scstrsplit(scstr_t string, scstr_t delim, ssize_t *count); | 643 sstr_t* scstrsplit(scstr_t string, scstr_t delim, ssize_t *count); |
611 | 644 |
612 /** | 645 /** |
613 * Alias for scstrsplit() which automatically converts the arguments. | 646 * Splits a string into parts by using a delimiter string. |
614 * | 647 * |
648 * This function will return <code>NULL</code>, if one of the following happens: | |
649 * <ul> | |
650 * <li>the string length is zero</li> | |
651 * <li>the delimeter length is zero</li> | |
652 * <li>the string equals the delimeter</li> | |
653 * <li>memory allocation fails</li> | |
654 * </ul> | |
655 * | |
656 * The integer referenced by <code>count</code> is used as input and determines | |
657 * the maximum size of the resulting array, i.e. the maximum count of splits to | |
658 * perform + 1. | |
659 * | |
660 * The integer referenced by <code>count</code> is also used as output and is | |
661 * set to | |
662 * <ul> | |
663 * <li>-2, on memory allocation errors</li> | |
664 * <li>-1, if either the string or the delimiter is an empty string</li> | |
665 * <li>0, if the string equals the delimiter</li> | |
666 * <li>1, if the string does not contain the delimiter</li> | |
667 * <li>the count of array items, otherwise</li> | |
668 * </ul> | |
669 * | |
670 * If the string starts with the delimiter, the first item of the resulting | |
671 * array will be an empty string. | |
672 * | |
673 * If the string ends with the delimiter and the maximum list size is not | |
674 * exceeded, the last array item will be an empty string. | |
675 * In case the list size would be exceeded, the last array item will be the | |
676 * remaining string after the last split, <i>including</i> the terminating | |
677 * delimiter. | |
678 * | |
679 * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array | |
680 * items must be manually passed to <code>free()</code>. Use sstrsplit_a() with | |
681 * an allocator to managed memory, to avoid this. | |
682 * | |
615 * @param string the string to split | 683 * @param string the string to split |
616 * @param delim the delimiter string | 684 * @param delim the delimiter string |
617 * @param count IN: the maximum size of the resulting array (0 = no limit), | 685 * @param count IN: the maximum size of the resulting array (0 = no limit), |
618 * OUT: the actual size of the array | 686 * OUT: the actual size of the array |
619 * @return a sstr_t array containing the split strings or | 687 * @return a sstr_t array containing the split strings or |
630 * <i>Read the description of scstrsplit() for details.</i> | 698 * <i>Read the description of scstrsplit() for details.</i> |
631 * | 699 * |
632 * The memory for the sstr_t.ptr pointers of the array items and the memory for | 700 * The memory for the sstr_t.ptr pointers of the array items and the memory for |
633 * the sstr_t array itself are allocated by using the UcxAllocator.malloc() | 701 * the sstr_t array itself are allocated by using the UcxAllocator.malloc() |
634 * function. | 702 * function. |
635 * | |
636 * <b>Note:</b> the allocator is not used for memory that is freed within the | |
637 * same call of this function (locally scoped variables). | |
638 * | 703 * |
639 * @param allocator the UcxAllocator used for allocating memory | 704 * @param allocator the UcxAllocator used for allocating memory |
640 * @param string the string to split | 705 * @param string the string to split |
641 * @param delim the delimiter string | 706 * @param delim the delimiter string |
642 * @param count IN: the maximum size of the resulting array (0 = no limit), | 707 * @param count IN: the maximum size of the resulting array (0 = no limit), |
648 */ | 713 */ |
649 sstr_t* scstrsplit_a(UcxAllocator *allocator, scstr_t string, scstr_t delim, | 714 sstr_t* scstrsplit_a(UcxAllocator *allocator, scstr_t string, scstr_t delim, |
650 ssize_t *count); | 715 ssize_t *count); |
651 | 716 |
652 /** | 717 /** |
653 * Alias for scstrsplit_a() which automatically converts the arguments. | 718 * Performing sstrsplit() using a UcxAllocator. |
719 * | |
720 * <i>Read the description of sstrsplit() for details.</i> | |
721 * | |
722 * The memory for the sstr_t.ptr pointers of the array items and the memory for | |
723 * the sstr_t array itself are allocated by using the UcxAllocator.malloc() | |
724 * function. | |
654 * | 725 * |
655 * @param allocator the UcxAllocator used for allocating memory | 726 * @param allocator the UcxAllocator used for allocating memory |
656 * @param string the string to split | 727 * @param string the string to split |
657 * @param delim the delimiter string | 728 * @param delim the delimiter string |
658 * @param count IN: the maximum size of the resulting array (0 = no limit), | 729 * @param count IN: the maximum size of the resulting array (0 = no limit), |
678 * <code>memcmp()</code> otherwise (i.e. 0 if the strings match) | 749 * <code>memcmp()</code> otherwise (i.e. 0 if the strings match) |
679 */ | 750 */ |
680 int scstrcmp(scstr_t s1, scstr_t s2); | 751 int scstrcmp(scstr_t s1, scstr_t s2); |
681 | 752 |
682 /** | 753 /** |
683 * Alias for scstrcmp() which automatically converts its arguments. | 754 * Compares two UCX strings with standard <code>memcmp()</code>. |
755 * | |
756 * At first it compares the sstr_t.length attribute of the two strings. The | |
757 * <code>memcmp()</code> function is called, if and only if the lengths match. | |
684 * | 758 * |
685 * @param s1 the first string | 759 * @param s1 the first string |
686 * @param s2 the second string | 760 * @param s2 the second string |
687 * @return -1, if the length of s1 is less than the length of s2 or 1, if the | 761 * @return -1, if the length of s1 is less than the length of s2 or 1, if the |
688 * length of s1 is greater than the length of s2 or the result of | 762 * length of s1 is greater than the length of s2 or the result of |
704 * specific string comparison function ignoring the case. | 778 * specific string comparison function ignoring the case. |
705 */ | 779 */ |
706 int scstrcasecmp(scstr_t s1, scstr_t s2); | 780 int scstrcasecmp(scstr_t s1, scstr_t s2); |
707 | 781 |
708 /** | 782 /** |
709 * Alias for scstrcasecmp() which automatically converts the arguments. | 783 * Compares two UCX strings ignoring the case. |
784 * | |
785 * At first it compares the sstr_t.length attribute of the two strings. If and | |
786 * only if the lengths match, both strings are compared char by char ignoring | |
787 * the case. | |
710 * | 788 * |
711 * @param s1 the first string | 789 * @param s1 the first string |
712 * @param s2 the second string | 790 * @param s2 the second string |
713 * @return -1, if the length of s1 is less than the length of s2 or 1, if the | 791 * @return -1, if the length of s1 is less than the length of s2 or 1, if the |
714 * length of s1 is greater than the length of s2 or the result of the platform | 792 * length of s1 is greater than the length of s2 or the result of the platform |
731 * @see scstrdup_a() | 809 * @see scstrdup_a() |
732 */ | 810 */ |
733 sstr_t scstrdup(scstr_t string); | 811 sstr_t scstrdup(scstr_t string); |
734 | 812 |
735 /** | 813 /** |
736 * Alias for scstrdup() which automatically converts the argument. | 814 * Creates a duplicate of the specified string. |
815 * | |
816 * The new sstr_t will contain a copy allocated by standard | |
817 * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to | |
818 * <code>free()</code>. | |
819 * | |
820 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>- | |
821 * terminated, regardless of the argument. | |
737 * | 822 * |
738 * @param string the string to duplicate | 823 * @param string the string to duplicate |
739 * @return a duplicate of the string | 824 * @return a duplicate of the string |
740 * @see sstrdup_a() | 825 * @see sstrdup_a() |
741 */ | 826 */ |
758 * @see scstrdup() | 843 * @see scstrdup() |
759 */ | 844 */ |
760 sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t string); | 845 sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t string); |
761 | 846 |
762 /** | 847 /** |
763 * Alias for scstrdup_a() which automatically converts the argument. | 848 * Creates a duplicate of the specified string using a UcxAllocator. |
849 * | |
850 * The new sstr_t will contain a copy allocated by the allocators | |
851 * UcxAllocator.malloc() function. So it is implementation depended, whether the | |
852 * returned sstr_t.ptr pointer must be passed to the allocators | |
853 * UcxAllocator.free() function manually. | |
854 * | |
855 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>- | |
856 * terminated, regardless of the argument. | |
764 * | 857 * |
765 * @param allocator a valid instance of a UcxAllocator | 858 * @param allocator a valid instance of a UcxAllocator |
766 * @param string the string to duplicate | 859 * @param string the string to duplicate |
767 * @return a duplicate of the string | 860 * @return a duplicate of the string |
768 * @see scstrdup() | 861 * @see scstrdup() |
808 */ | 901 */ |
809 scstr_t scstrtrim(scstr_t string); | 902 scstr_t scstrtrim(scstr_t string); |
810 | 903 |
811 /** | 904 /** |
812 * Checks, if a string has a specific prefix. | 905 * Checks, if a string has a specific prefix. |
906 * | |
813 * @param string the string to check | 907 * @param string the string to check |
814 * @param prefix the prefix the string should have | 908 * @param prefix the prefix the string should have |
815 * @return 1, if and only if the string has the specified prefix, 0 otherwise | 909 * @return 1, if and only if the string has the specified prefix, 0 otherwise |
816 */ | 910 */ |
817 int scstrprefix(scstr_t string, scstr_t prefix); | 911 int scstrprefix(scstr_t string, scstr_t prefix); |
818 | 912 |
819 /** | 913 /** |
820 * Alias for scstrprefix() which automatically converts the arguments. | 914 * Checks, if a string has a specific prefix. |
821 * | 915 * |
822 * @param string the string to check | 916 * @param string the string to check |
823 * @param prefix the prefix the string should have | 917 * @param prefix the prefix the string should have |
824 * @return 1, if and only if the string has the specified prefix, 0 otherwise | 918 * @return 1, if and only if the string has the specified prefix, 0 otherwise |
825 */ | 919 */ |
826 #define sstrprefix(string, prefix) scstrprefix(SCSTR(string), SCSTR(prefix)) | 920 #define sstrprefix(string, prefix) scstrprefix(SCSTR(string), SCSTR(prefix)) |
827 | 921 |
828 /** | 922 /** |
829 * Checks, if a string has a specific suffix. | 923 * Checks, if a string has a specific suffix. |
924 * | |
830 * @param string the string to check | 925 * @param string the string to check |
831 * @param suffix the suffix the string should have | 926 * @param suffix the suffix the string should have |
832 * @return 1, if and only if the string has the specified suffix, 0 otherwise | 927 * @return 1, if and only if the string has the specified suffix, 0 otherwise |
833 */ | 928 */ |
834 int scstrsuffix(scstr_t string, scstr_t suffix); | 929 int scstrsuffix(scstr_t string, scstr_t suffix); |
835 | 930 |
836 /** | 931 /** |
837 * Alias for scstrsuffix() which automatically converts the arguments. | 932 * Checks, if a string has a specific suffix. |
838 * | 933 * |
839 * @param string the string to check | 934 * @param string the string to check |
840 * @param suffix the suffix the string should have | 935 * @param suffix the suffix the string should have |
841 * @return 1, if and only if the string has the specified suffix, 0 otherwise | 936 * @return 1, if and only if the string has the specified suffix, 0 otherwise |
842 */ | 937 */ |
843 #define sstrsuffix(string, suffix) scstrsuffix(SCSTR(string), SCSTR(suffix)) | 938 #define sstrsuffix(string, suffix) scstrsuffix(SCSTR(string), SCSTR(suffix)) |
844 | 939 |
845 /** | 940 /** |
846 * Returns a lower case version of a string. | 941 * Returns a lower case version of a string. |
847 * | 942 * |
848 * This function creates a duplicate of the input string, first. See the | 943 * This function creates a duplicate of the input string, first |
849 * documentation of scstrdup() for the implications. | 944 * (see scstrdup()). |
850 * | 945 * |
851 * @param string the input string | 946 * @param string the input string |
852 * @return the resulting lower case string | 947 * @return the resulting lower case string |
853 * @see scstrdup() | 948 * @see scstrdup() |
854 */ | 949 */ |
855 sstr_t scstrlower(scstr_t string); | 950 sstr_t scstrlower(scstr_t string); |
856 | 951 |
857 /** | 952 /** |
858 * Alias for scstrlower() which automatically converts the argument. | 953 * Returns a lower case version of a string. |
954 * | |
955 * This function creates a duplicate of the input string, first | |
956 * (see sstrdup()). | |
859 * | 957 * |
860 * @param string the input string | 958 * @param string the input string |
861 * @return the resulting lower case string | 959 * @return the resulting lower case string |
862 */ | 960 */ |
863 #define sstrlower(string) scstrlower(SCSTR(string)) | 961 #define sstrlower(string) scstrlower(SCSTR(string)) |
864 | 962 |
865 /** | 963 /** |
866 * Returns a lower case version of a string. | 964 * Returns a lower case version of a string. |
867 * | 965 * |
868 * This function creates a duplicate of the input string, first. See the | 966 * This function creates a duplicate of the input string, first |
869 * documentation of scstrdup_a() for the implications. | 967 * (see scstrdup_a()). |
870 * | 968 * |
871 * @param allocator the allocator used for duplicating the string | 969 * @param allocator the allocator used for duplicating the string |
872 * @param string the input string | 970 * @param string the input string |
873 * @return the resulting lower case string | 971 * @return the resulting lower case string |
874 * @see scstrdup_a() | 972 * @see scstrdup_a() |
875 */ | 973 */ |
876 sstr_t scstrlower_a(UcxAllocator *allocator, scstr_t string); | 974 sstr_t scstrlower_a(UcxAllocator *allocator, scstr_t string); |
877 | 975 |
878 | 976 |
879 /** | 977 /** |
880 * Alias for scstrlower_a() which automatically converts the argument. | 978 * Returns a lower case version of a string. |
979 * | |
980 * This function creates a duplicate of the input string, first | |
981 * (see sstrdup_a()). | |
881 * | 982 * |
882 * @param allocator the allocator used for duplicating the string | 983 * @param allocator the allocator used for duplicating the string |
883 * @param string the input string | 984 * @param string the input string |
884 * @return the resulting lower case string | 985 * @return the resulting lower case string |
885 */ | 986 */ |
886 #define sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string)) | 987 #define sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string)) |
887 | 988 |
888 /** | 989 /** |
889 * Returns a upper case version of a string. | 990 * Returns a upper case version of a string. |
890 * | 991 * |
891 * This function creates a duplicate of the input string, first. See the | 992 * This function creates a duplicate of the input string, first |
892 * documentation of scstrdup() for the implications. | 993 * (see scstrdup()). |
893 * | 994 * |
894 * @param string the input string | 995 * @param string the input string |
895 * @return the resulting upper case string | 996 * @return the resulting upper case string |
896 * @see scstrdup() | 997 * @see scstrdup() |
897 */ | 998 */ |
898 sstr_t scstrupper(scstr_t string); | 999 sstr_t scstrupper(scstr_t string); |
899 | 1000 |
900 /** | 1001 /** |
901 * Alias for scstrupper() which automatically converts the argument. | 1002 * Returns a upper case version of a string. |
1003 * | |
1004 * This function creates a duplicate of the input string, first | |
1005 * (see sstrdup()). | |
902 * | 1006 * |
903 * @param string the input string | 1007 * @param string the input string |
904 * @return the resulting upper case string | 1008 * @return the resulting upper case string |
905 */ | 1009 */ |
906 #define sstrupper(string) scstrupper(SCSTR(string)) | 1010 #define sstrupper(string) scstrupper(SCSTR(string)) |
907 | 1011 |
908 /** | 1012 /** |
909 * Returns a upper case version of a string. | 1013 * Returns a upper case version of a string. |
910 * | 1014 * |
911 * This function creates a duplicate of the input string, first. See the | 1015 * This function creates a duplicate of the input string, first |
912 * documentation of scstrdup_a() for the implications. | 1016 * (see scstrdup_a()). |
913 * | 1017 * |
914 * @param allocator the allocator used for duplicating the string | 1018 * @param allocator the allocator used for duplicating the string |
915 * @param string the input string | 1019 * @param string the input string |
916 * @return the resulting upper case string | 1020 * @return the resulting upper case string |
917 * @see scstrdup_a() | 1021 * @see scstrdup_a() |
918 */ | 1022 */ |
919 sstr_t scstrupper_a(UcxAllocator *allocator, scstr_t string); | 1023 sstr_t scstrupper_a(UcxAllocator *allocator, scstr_t string); |
920 | 1024 |
921 /** | 1025 /** |
922 * Alias for scstrupper_a() which automatically converts the argument. | 1026 * Returns a upper case version of a string. |
1027 * | |
1028 * This function creates a duplicate of the input string, first | |
1029 * (see sstrdup_a()). | |
923 * | 1030 * |
924 * @param allocator the allocator used for duplicating the string | 1031 * @param allocator the allocator used for duplicating the string |
925 * @param string the input string | 1032 * @param string the input string |
926 * @return the resulting upper case string | 1033 * @return the resulting upper case string |
927 */ | 1034 */ |