comparison: ucx/cx/string.h
ucx/cx/string.h
- changeset 748
- 49a284f61e8c
- parent 747
- efbd59642577
equal
deleted
inserted
replaced
| 747:efbd59642577 | 748:49a284f61e8c |
|---|---|
| 294 size_t count, | 294 size_t count, |
| 295 ... | 295 ... |
| 296 ); | 296 ); |
| 297 | 297 |
| 298 /** | 298 /** |
| 299 * Concatenates two or more strings. | 299 * Concatenates strings. |
| 300 * | 300 * |
| 301 * The resulting string will be allocated by the specified allocator. | 301 * The resulting string will be allocated by the specified allocator. |
| 302 * So developers \em must pass the return value to cx_strfree() eventually. | 302 * So developers \em must pass the return value to cx_strfree_a() eventually. |
| 303 * | 303 * |
| 304 * \note It is guaranteed that there is only one allocation. | 304 * If \p str already contains a string, the memory will be reallocated and |
| 305 * It is also guaranteed that the returned string is zero-terminated. | 305 * the other strings are appended. Otherwise, new memory is allocated. |
| 306 * | |
| 307 * \note It is guaranteed that there is only one allocation. | |
| 308 * It is also guaranteed that the returned string is zero-terminated. | |
| 306 * | 309 * |
| 307 * @param alloc the allocator to use | 310 * @param alloc the allocator to use |
| 308 * @param count the total number of strings to concatenate | 311 * @param str the string the other strings shall be concatenated to |
| 309 * @param ... all strings | 312 * @param count the number of the other following strings to concatenate |
| 313 * @param ... all other strings | |
| 310 * @return the concatenated string | 314 * @return the concatenated string |
| 311 */ | 315 */ |
| 312 __attribute__((__warn_unused_result__, __nonnull__)) | 316 __attribute__((__warn_unused_result__, __nonnull__)) |
| 313 cxmutstr cx_strcat_a( | 317 cxmutstr cx_strcat_ma( |
| 314 CxAllocator const *alloc, | 318 CxAllocator const *alloc, |
| 319 cxmutstr str, | |
| 315 size_t count, | 320 size_t count, |
| 316 ... | 321 ... |
| 317 ); | 322 ); |
| 318 | 323 |
| 319 /** | 324 /** |
| 320 * Concatenates two or more strings. | 325 * Concatenates strings and returns a new string. |
| 326 * | |
| 327 * The resulting string will be allocated by the specified allocator. | |
| 328 * So developers \em must pass the return value to cx_strfree_a() eventually. | |
| 329 * | |
| 330 * \note It is guaranteed that there is only one allocation. | |
| 331 * It is also guaranteed that the returned string is zero-terminated. | |
| 332 * | |
| 333 * @param alloc the allocator to use | |
| 334 * @param count the number of the other following strings to concatenate | |
| 335 * @param ... all other strings | |
| 336 * @return the concatenated string | |
| 337 */ | |
| 338 #define cx_strcat_a(alloc, count, ...) \ | |
| 339 cx_strcat_ma(alloc, cx_mutstrn(NULL, 0), count, __VA_ARGS__) | |
| 340 | |
| 341 /** | |
| 342 * Concatenates strings and returns a new string. | |
| 321 * | 343 * |
| 322 * The resulting string will be allocated by standard \c malloc(). | 344 * The resulting string will be allocated by standard \c malloc(). |
| 323 * So developers \em must pass the return value to cx_strfree() eventually. | 345 * So developers \em must pass the return value to cx_strfree() eventually. |
| 324 * | 346 * |
| 325 * \note It is guaranteed that there is only one allocation. | 347 * \note It is guaranteed that there is only one allocation. |
| 326 * It is also guaranteed that the returned string is zero-terminated. | 348 * It is also guaranteed that the returned string is zero-terminated. |
| 327 * | 349 * |
| 328 * @param count the total number of strings to concatenate | 350 * @param count the number of the other following strings to concatenate |
| 329 * @param ... all strings | 351 * @param ... all other strings |
| 330 * @return the concatenated string | 352 * @return the concatenated string |
| 331 */ | 353 */ |
| 332 #define cx_strcat(count, ...) \ | 354 #define cx_strcat(count, ...) \ |
| 333 cx_strcat_a(cxDefaultAllocator, count, __VA_ARGS__) | 355 cx_strcat_ma(cxDefaultAllocator, cx_mutstrn(NULL, 0), count, __VA_ARGS__) |
| 356 | |
| 357 /** | |
| 358 * Concatenates strings. | |
| 359 * | |
| 360 * The resulting string will be allocated by standard \c malloc(). | |
| 361 * So developers \em must pass the return value to cx_strfree() eventually. | |
| 362 * | |
| 363 * If \p str already contains a string, the memory will be reallocated and | |
| 364 * the other strings are appended. Otherwise, new memory is allocated. | |
| 365 * | |
| 366 * \note It is guaranteed that there is only one allocation. | |
| 367 * It is also guaranteed that the returned string is zero-terminated. | |
| 368 * | |
| 369 * @param str the string the other strings shall be concatenated to | |
| 370 * @param count the number of the other following strings to concatenate | |
| 371 * @param ... all other strings | |
| 372 * @return the concatenated string | |
| 373 */ | |
| 374 #define cx_strcat_m(str, count, ...) \ | |
| 375 cx_strcat_ma(cxDefaultAllocator, str, count, __VA_ARGS__) | |
| 334 | 376 |
| 335 /** | 377 /** |
| 336 * Returns a substring starting at the specified location. | 378 * Returns a substring starting at the specified location. |
| 337 * | 379 * |
| 338 * \attention the new string references the same memory area as the | 380 * \attention the new string references the same memory area as the |
| 730 * @return a duplicate of the string | 772 * @return a duplicate of the string |
| 731 * @see cx_strdup_a() | 773 * @see cx_strdup_a() |
| 732 */ | 774 */ |
| 733 #define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string) | 775 #define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string) |
| 734 | 776 |
| 777 | |
| 778 /** | |
| 779 * Creates a duplicate of the specified string. | |
| 780 * | |
| 781 * The new string will contain a copy allocated by \p allocator. | |
| 782 * | |
| 783 * \note The returned string is guaranteed to be zero-terminated. | |
| 784 * | |
| 785 * @param allocator the allocator to use | |
| 786 * @param string the string to duplicate | |
| 787 * @return a duplicate of the string | |
| 788 * @see cx_strdup_m() | |
| 789 */ | |
| 790 #define cx_strdup_ma(allocator, string) cx_strdup_a(allocator, cx_strcast(string)) | |
| 791 | |
| 792 /** | |
| 793 * Creates a duplicate of the specified string. | |
| 794 * | |
| 795 * The new string will contain a copy allocated by standard | |
| 796 * \c malloc(). So developers \em must pass the return value to cx_strfree(). | |
| 797 * | |
| 798 * \note The returned string is guaranteed to be zero-terminated. | |
| 799 * | |
| 800 * @param string the string to duplicate | |
| 801 * @return a duplicate of the string | |
| 802 * @see cx_strdup_ma() | |
| 803 */ | |
| 804 #define cx_strdup_m(string) cx_strdup_a(cxDefaultAllocator, cx_strcast(string)) | |
| 805 | |
| 735 /** | 806 /** |
| 736 * Omits leading and trailing spaces. | 807 * Omits leading and trailing spaces. |
| 737 * | 808 * |
| 738 * \note the returned string references the same memory, thus you | 809 * \note the returned string references the same memory, thus you |
| 739 * must \em not free the returned memory. | 810 * must \em not free the returned memory. |
