1.1 --- a/ucx/string.h Wed Jul 17 16:17:42 2013 +0200
1.2 +++ b/ucx/string.h Wed Jul 17 20:03:01 2013 +0200
1.3 @@ -183,12 +183,48 @@
1.4 * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
1.5 * <code>free()</code>.
1.6 *
1.7 + * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.8 + * terminated.
1.9 + *
1.10 * @param string the string to duplicate
1.11 - * @return a duplicate of the argument
1.12 + * @return a duplicate of the string
1.13 */
1.14 sstr_t sstrdup(sstr_t string);
1.15 -sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
1.16
1.17 +/**
1.18 + * Creates a duplicate of the specified string using an UcxAllocator.
1.19 + *
1.20 + * The new sstr_t will contain a copy allocated by the allocators
1.21 + * ucx_allocator_malloc function. So it is implementation depended, whether the
1.22 + * returned sstr_t.ptr pointer must be passed to the allocators
1.23 + * ucx_allocator_free function manually.
1.24 + *
1.25 + * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.26 + * terminated.
1.27 + *
1.28 + * @param allocator a valid instance of an UcxAllocator
1.29 + * @param string the string to duplicate
1.30 + * @return a duplicate of the string
1.31 + */
1.32 +sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string);
1.33 +
1.34 +/**
1.35 + * Omits leading and trailing spaces.
1.36 + *
1.37 + * This function returns a new sstr_t containing a trimmed version of the
1.38 + * specified string.
1.39 + *
1.40 + * <b>Note:</b> the new sstr_t references the same memory, thus you
1.41 + * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
1.42 + * <code>free()</code>. It is also highly recommended to avoid assignments like
1.43 + * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
1.44 + * source string. Assignments of this type are only permitted, if the
1.45 + * sstr_t.ptr of the source string does not need to be freed or if another
1.46 + * reference to the source string exists.
1.47 + *
1.48 + * @param string the string that shall be trimmed
1.49 + * @return a new sstr_t containing the trimmed string
1.50 + */
1.51 sstr_t sstrtrim(sstr_t string);
1.52
1.53 #ifdef __cplusplus
