comparison: src/cx/string.h
src/cx/string.h
- changeset 1667
- 608cc0b25352
- parent 1652
- db8299984bfe
- child 1668
- 3ffdfe1776b4
equal
deleted
inserted
replaced
| 1665:b79405fbf91d | 1667:608cc0b25352 |
|---|---|
| 414 * So developers @em must pass the return value to cx_strfree_a() eventually. | 414 * So developers @em must pass the return value to cx_strfree_a() eventually. |
| 415 * | 415 * |
| 416 * If @p str already contains a string, the memory will be reallocated and | 416 * If @p str already contains a string, the memory will be reallocated and |
| 417 * the other strings are appended. Otherwise, new memory is allocated. | 417 * the other strings are appended. Otherwise, new memory is allocated. |
| 418 * | 418 * |
| 419 * If memory allocation fails, the pointer in the returned string will | |
| 420 * be @c NULL. Depending on the allocator, @c errno might be set. | |
| 421 * | |
| 422 * @note It is guaranteed that there is only one allocation for the | 419 * @note It is guaranteed that there is only one allocation for the |
| 423 * resulting string. | 420 * resulting string. |
| 424 * It is also guaranteed that the returned string is zero-terminated. | 421 * It is also guaranteed that the returned string is zero-terminated. |
| 425 * | 422 * |
| 426 * @param alloc the allocator to use | 423 * @param alloc the allocator to use |
| 427 * @param str the string the other strings shall be concatenated to | 424 * @param str the string the other strings shall be concatenated to |
| 428 * @param count the number of the other following strings to concatenate | 425 * @param count the number of the other following strings to concatenate |
| 429 * @param ... all other UCX strings | 426 * @param ... all other UCX strings |
| 430 * @return the concatenated string | 427 * @retval zero success |
| 431 */ | 428 * @retval non-zero allocation failure |
| 432 cx_attr_nodiscard cx_attr_nonnull | 429 */ |
| 433 CX_EXPORT cxmutstr cx_strcat_ma(const CxAllocator *alloc, | 430 cx_attr_nonnull |
| 434 cxmutstr str, size_t count, ...); | 431 CX_EXPORT int cx_strcat_a(const CxAllocator *alloc, |
| 432 cxmutstr *str, size_t count, ...); | |
| 435 | 433 |
| 436 /** | 434 /** |
| 437 * Concatenates strings and returns a new string. | 435 * Concatenates strings and returns a new string. |
| 438 * | 436 * |
| 439 * The resulting string will be allocated by the specified allocator. | 437 * The resulting string will be allocated by the cxDefaultAllocator. |
| 440 * So developers @em must pass the return value to cx_strfree_a() eventually. | 438 * So developers @em must pass the return value to cx_strfree() eventually. |
| 441 * | |
| 442 * If memory allocation fails, the pointer in the returned string will | |
| 443 * be @c NULL. Depending on the allocator, @c errno might be set. | |
| 444 * | 439 * |
| 445 * @note It is guaranteed that there is only one allocation for the | 440 * @note It is guaranteed that there is only one allocation for the |
| 446 * resulting string. | 441 * resulting string. |
| 447 * It is also guaranteed that the returned string is zero-terminated. | 442 * It is also guaranteed that the returned string is zero-terminated. |
| 448 * | 443 * |
| 449 * @param alloc (@c CxAllocator*) the allocator to use | 444 * @param str (@c cxmutstr*) the string the other strings shall be concatenated to |
| 450 * @param count (@c size_t) the number of the other following strings to concatenate | |
| 451 * @param ... all other UCX strings | |
| 452 * @return (@c cxmutstr) the concatenated string | |
| 453 */ | |
| 454 #define cx_strcat_a(alloc, count, ...) \ | |
| 455 cx_strcat_ma(alloc, cx_mutstrn(NULL, 0), count, __VA_ARGS__) | |
| 456 | |
| 457 /** | |
| 458 * Concatenates strings and returns a new string. | |
| 459 * | |
| 460 * The resulting string will be allocated by the cxDefaultAllocator. | |
| 461 * So developers @em must pass the return value to cx_strfree() eventually. | |
| 462 * | |
| 463 * If memory allocation fails, the pointer in the returned string will | |
| 464 * be @c NULL and @c errno might be set. | |
| 465 * | |
| 466 * @note It is guaranteed that there is only one allocation for the | |
| 467 * resulting string. | |
| 468 * It is also guaranteed that the returned string is zero-terminated. | |
| 469 * | |
| 470 * @param count (@c size_t) the number of the other following strings to concatenate | 445 * @param count (@c size_t) the number of the other following strings to concatenate |
| 471 * @param ... all other UCX strings | 446 * @param ... all other UCX strings |
| 472 * @return (@c cxmutstr) the concatenated string | 447 * @retval zero success |
| 473 */ | 448 * @retval non-zero allocation failure |
| 474 #define cx_strcat(count, ...) \ | 449 */ |
| 475 cx_strcat_ma(cxDefaultAllocator, cx_mutstrn(NULL, 0), count, __VA_ARGS__) | 450 #define cx_strcat(str, count, ...) \ |
| 476 | 451 cx_strcat_a(cxDefaultAllocator, str, count, __VA_ARGS__) |
| 477 /** | |
| 478 * Concatenates strings. | |
| 479 * | |
| 480 * The resulting string will be allocated by the cxDefaultAllocator. | |
| 481 * So developers @em must pass the return value to cx_strfree() eventually. | |
| 482 * | |
| 483 * If @p str already contains a string, the memory will be reallocated and | |
| 484 * the other strings are appended. Otherwise, new memory is allocated. | |
| 485 * | |
| 486 * If memory allocation fails, the pointer in the returned string will | |
| 487 * be @c NULL and @c errno might be set. | |
| 488 * | |
| 489 * @note It is guaranteed that there is only one allocation for the | |
| 490 * resulting string. | |
| 491 * It is also guaranteed that the returned string is zero-terminated. | |
| 492 * | |
| 493 * @param str (@c cxmutstr) the string the other strings shall be concatenated to | |
| 494 * @param count (@c size_t) the number of the other following strings to concatenate | |
| 495 * @param ... all other strings | |
| 496 * @return (@c cxmutstr) the concatenated string | |
| 497 */ | |
| 498 #define cx_strcat_m(str, count, ...) \ | |
| 499 cx_strcat_ma(cxDefaultAllocator, str, count, __VA_ARGS__) | |
| 500 | 452 |
| 501 /** | 453 /** |
| 502 * Returns a substring starting at the specified location. | 454 * Returns a substring starting at the specified location. |
| 503 * | 455 * |
| 504 * @attention the new string references the same memory area as the | 456 * @attention the new string references the same memory area as the |
