161:b1eac0878ce7 | 162:18892c0a9adc |
---|---|
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 /** |
941 * Checks, if a string has a specific prefix, ignoring the case. | |
942 * | |
943 * @param string the string to check | |
944 * @param prefix the prefix the string should have | |
945 * @return 1, if and only if the string has the specified prefix, 0 otherwise | |
946 */ | |
947 int scstrcaseprefix(scstr_t string, scstr_t prefix); | |
948 | |
949 /** | |
950 * Checks, if a string has a specific prefix, ignoring the case. | |
951 * | |
952 * @param string the string to check | |
953 * @param prefix the prefix the string should have | |
954 * @return 1, if and only if the string has the specified prefix, 0 otherwise | |
955 */ | |
956 #define sstrcaseprefix(string, prefix) \ | |
957 scstrcaseprefix(SCSTR(string), SCSTR(prefix)) | |
958 | |
959 /** | |
960 * Checks, if a string has a specific suffix, ignoring the case. | |
961 * | |
962 * @param string the string to check | |
963 * @param suffix the suffix the string should have | |
964 * @return 1, if and only if the string has the specified suffix, 0 otherwise | |
965 */ | |
966 int scstrcasesuffix(scstr_t string, scstr_t suffix); | |
967 | |
968 /** | |
969 * Checks, if a string has a specific suffix, ignoring the case. | |
970 * | |
971 * @param string the string to check | |
972 * @param suffix the suffix the string should have | |
973 * @return 1, if and only if the string has the specified suffix, 0 otherwise | |
974 */ | |
975 #define sstrcasesuffix(string, suffix) \ | |
976 scstrcasesuffix(SCSTR(string), SCSTR(suffix)) | |
977 | |
978 /** | |
846 * Returns a lower case version of a string. | 979 * Returns a lower case version of a string. |
847 * | 980 * |
848 * This function creates a duplicate of the input string, first. See the | 981 * This function creates a duplicate of the input string, first |
849 * documentation of scstrdup() for the implications. | 982 * (see scstrdup()). |
850 * | 983 * |
851 * @param string the input string | 984 * @param string the input string |
852 * @return the resulting lower case string | 985 * @return the resulting lower case string |
853 * @see scstrdup() | 986 * @see scstrdup() |
854 */ | 987 */ |
855 sstr_t scstrlower(scstr_t string); | 988 sstr_t scstrlower(scstr_t string); |
856 | 989 |
857 /** | 990 /** |
858 * Alias for scstrlower() which automatically converts the argument. | 991 * Returns a lower case version of a string. |
992 * | |
993 * This function creates a duplicate of the input string, first | |
994 * (see sstrdup()). | |
859 * | 995 * |
860 * @param string the input string | 996 * @param string the input string |
861 * @return the resulting lower case string | 997 * @return the resulting lower case string |
862 */ | 998 */ |
863 #define sstrlower(string) scstrlower(SCSTR(string)) | 999 #define sstrlower(string) scstrlower(SCSTR(string)) |
864 | 1000 |
865 /** | 1001 /** |
866 * Returns a lower case version of a string. | 1002 * Returns a lower case version of a string. |
867 * | 1003 * |
868 * This function creates a duplicate of the input string, first. See the | 1004 * This function creates a duplicate of the input string, first |
869 * documentation of scstrdup_a() for the implications. | 1005 * (see scstrdup_a()). |
870 * | 1006 * |
871 * @param allocator the allocator used for duplicating the string | 1007 * @param allocator the allocator used for duplicating the string |
872 * @param string the input string | 1008 * @param string the input string |
873 * @return the resulting lower case string | 1009 * @return the resulting lower case string |
874 * @see scstrdup_a() | 1010 * @see scstrdup_a() |
875 */ | 1011 */ |
876 sstr_t scstrlower_a(UcxAllocator *allocator, scstr_t string); | 1012 sstr_t scstrlower_a(UcxAllocator *allocator, scstr_t string); |
877 | 1013 |
878 | 1014 |
879 /** | 1015 /** |
880 * Alias for scstrlower_a() which automatically converts the argument. | 1016 * Returns a lower case version of a string. |
1017 * | |
1018 * This function creates a duplicate of the input string, first | |
1019 * (see sstrdup_a()). | |
881 * | 1020 * |
882 * @param allocator the allocator used for duplicating the string | 1021 * @param allocator the allocator used for duplicating the string |
883 * @param string the input string | 1022 * @param string the input string |
884 * @return the resulting lower case string | 1023 * @return the resulting lower case string |
885 */ | 1024 */ |
886 #define sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string)) | 1025 #define sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string)) |
887 | 1026 |
888 /** | 1027 /** |
889 * Returns a upper case version of a string. | 1028 * Returns a upper case version of a string. |
890 * | 1029 * |
891 * This function creates a duplicate of the input string, first. See the | 1030 * This function creates a duplicate of the input string, first |
892 * documentation of scstrdup() for the implications. | 1031 * (see scstrdup()). |
893 * | 1032 * |
894 * @param string the input string | 1033 * @param string the input string |
895 * @return the resulting upper case string | 1034 * @return the resulting upper case string |
896 * @see scstrdup() | 1035 * @see scstrdup() |
897 */ | 1036 */ |
898 sstr_t scstrupper(scstr_t string); | 1037 sstr_t scstrupper(scstr_t string); |
899 | 1038 |
900 /** | 1039 /** |
901 * Alias for scstrupper() which automatically converts the argument. | 1040 * Returns a upper case version of a string. |
1041 * | |
1042 * This function creates a duplicate of the input string, first | |
1043 * (see sstrdup()). | |
902 * | 1044 * |
903 * @param string the input string | 1045 * @param string the input string |
904 * @return the resulting upper case string | 1046 * @return the resulting upper case string |
905 */ | 1047 */ |
906 #define sstrupper(string) scstrupper(SCSTR(string)) | 1048 #define sstrupper(string) scstrupper(SCSTR(string)) |
907 | 1049 |
908 /** | 1050 /** |
909 * Returns a upper case version of a string. | 1051 * Returns a upper case version of a string. |
910 * | 1052 * |
911 * This function creates a duplicate of the input string, first. See the | 1053 * This function creates a duplicate of the input string, first |
912 * documentation of scstrdup_a() for the implications. | 1054 * (see scstrdup_a()). |
913 * | 1055 * |
914 * @param allocator the allocator used for duplicating the string | 1056 * @param allocator the allocator used for duplicating the string |
915 * @param string the input string | 1057 * @param string the input string |
916 * @return the resulting upper case string | 1058 * @return the resulting upper case string |
917 * @see scstrdup_a() | 1059 * @see scstrdup_a() |
918 */ | 1060 */ |
919 sstr_t scstrupper_a(UcxAllocator *allocator, scstr_t string); | 1061 sstr_t scstrupper_a(UcxAllocator *allocator, scstr_t string); |
920 | 1062 |
921 /** | 1063 /** |
922 * Alias for scstrupper_a() which automatically converts the argument. | 1064 * Returns a upper case version of a string. |
1065 * | |
1066 * This function creates a duplicate of the input string, first | |
1067 * (see sstrdup_a()). | |
923 * | 1068 * |
924 * @param allocator the allocator used for duplicating the string | 1069 * @param allocator the allocator used for duplicating the string |
925 * @param string the input string | 1070 * @param string the input string |
926 * @return the resulting upper case string | 1071 * @return the resulting upper case string |
927 */ | 1072 */ |
928 #define sstrupper_a(allocator, string) scstrupper_a(allocator, string) | 1073 #define sstrupper_a(allocator, string) scstrupper_a(allocator, string) |
929 | 1074 |
1075 | |
1076 /** | |
1077 * Replaces a pattern in a string with another string. | |
1078 * | |
1079 * The pattern is taken literally and is no regular expression. | |
1080 * Replaces at most <code>replmax</code> occurrences. | |
1081 * | |
1082 * The resulting string is allocated by the specified allocator. I.e. it | |
1083 * depends on the used allocator, whether the sstr_t.ptr must be freed | |
1084 * manually. | |
1085 * | |
1086 * If allocation fails, the sstr_t.ptr of the return value is NULL. | |
1087 * | |
1088 * @param allocator the allocator to use | |
1089 * @param str the string where replacements should be applied | |
1090 * @param pattern the pattern to search for | |
1091 * @param replacement the replacement string | |
1092 * @param replmax maximum number of replacements | |
1093 * @return the resulting string after applying the replacements | |
1094 */ | |
1095 sstr_t scstrreplacen_a(UcxAllocator *allocator, scstr_t str, | |
1096 scstr_t pattern, scstr_t replacement, size_t replmax); | |
1097 | |
1098 /** | |
1099 * Replaces a pattern in a string with another string. | |
1100 * | |
1101 * The pattern is taken literally and is no regular expression. | |
1102 * Replaces at most <code>replmax</code> occurrences. | |
1103 * | |
1104 * The sstr_t.ptr of the resulting string must be freed manually. | |
1105 * | |
1106 * If allocation fails, the sstr_t.ptr of the return value is NULL. | |
1107 * | |
1108 * @param str the string where replacements should be applied | |
1109 * @param pattern the pattern to search for | |
1110 * @param replacement the replacement string | |
1111 * @param replmax maximum number of replacements | |
1112 * @return the resulting string after applying the replacements | |
1113 */ | |
1114 sstr_t scstrreplacen(scstr_t str, scstr_t pattern, | |
1115 scstr_t replacement, size_t replmax); | |
1116 | |
1117 /** | |
1118 * Replaces a pattern in a string with another string. | |
1119 * | |
1120 * The pattern is taken literally and is no regular expression. | |
1121 * Replaces at most <code>replmax</code> occurrences. | |
1122 * | |
1123 * The resulting string is allocated by the specified allocator. I.e. it | |
1124 * depends on the used allocator, whether the sstr_t.ptr must be freed | |
1125 * manually. | |
1126 * | |
1127 * @param allocator the allocator to use | |
1128 * @param str the string where replacements should be applied | |
1129 * @param pattern the pattern to search for | |
1130 * @param replacement the replacement string | |
1131 * @param replmax maximum number of replacements | |
1132 * @return the resulting string after applying the replacements | |
1133 */ | |
1134 #define sstrreplacen_a(allocator, str, pattern, replacement, replmax) \ | |
1135 scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \ | |
1136 SCSTR(replacement), replmax) | |
1137 | |
1138 /** | |
1139 * Replaces a pattern in a string with another string. | |
1140 * | |
1141 * The pattern is taken literally and is no regular expression. | |
1142 * Replaces at most <code>replmax</code> occurrences. | |
1143 * | |
1144 * The sstr_t.ptr of the resulting string must be freed manually. | |
1145 * | |
1146 * If allocation fails, the sstr_t.ptr of the return value is NULL. | |
1147 * | |
1148 * @param str the string where replacements should be applied | |
1149 * @param pattern the pattern to search for | |
1150 * @param replacement the replacement string | |
1151 * @param replmax maximum number of replacements | |
1152 * @return the resulting string after applying the replacements | |
1153 */ | |
1154 #define sstrreplacen(str, pattern, replacement, replmax) \ | |
1155 scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), replmax) | |
1156 | |
1157 /** | |
1158 * Replaces a pattern in a string with another string. | |
1159 * | |
1160 * The pattern is taken literally and is no regular expression. | |
1161 * Replaces at most <code>replmax</code> occurrences. | |
1162 * | |
1163 * The resulting string is allocated by the specified allocator. I.e. it | |
1164 * depends on the used allocator, whether the sstr_t.ptr must be freed | |
1165 * manually. | |
1166 * | |
1167 * If allocation fails, the sstr_t.ptr of the return value is NULL. | |
1168 * | |
1169 * @param allocator the allocator to use | |
1170 * @param str the string where replacements should be applied | |
1171 * @param pattern the pattern to search for | |
1172 * @param replacement the replacement string | |
1173 * @return the resulting string after applying the replacements | |
1174 */ | |
1175 #define sstrreplace_a(allocator, str, pattern, replacement) \ | |
1176 scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \ | |
1177 SCSTR(replacement), SIZE_MAX) | |
1178 | |
1179 /** | |
1180 * Replaces a pattern in a string with another string. | |
1181 * | |
1182 * The pattern is taken literally and is no regular expression. | |
1183 * Replaces at most <code>replmax</code> occurrences. | |
1184 * | |
1185 * The sstr_t.ptr of the resulting string must be freed manually. | |
1186 * | |
1187 * If allocation fails, the sstr_t.ptr of the return value is NULL. | |
1188 * | |
1189 * @param str the string where replacements should be applied | |
1190 * @param pattern the pattern to search for | |
1191 * @param replacement the replacement string | |
1192 * @return the resulting string after applying the replacements | |
1193 */ | |
1194 #define sstrreplace(str, pattern, replacement) \ | |
1195 scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), SIZE_MAX) | |
1196 | |
930 #ifdef __cplusplus | 1197 #ifdef __cplusplus |
931 } | 1198 } |
932 #endif | 1199 #endif |
933 | 1200 |
934 #endif /* UCX_STRING_H */ | 1201 #endif /* UCX_STRING_H */ |