dav: comparison ucx/cx/string.h

-:591377a27fa3
+:da79af4baec8
 #ifndef UCX_STRING_H
 #define UCX_STRING_H
 #include "common.h"
 #include "allocator.h"
+/** Expands a UCX string as printf arguments. */
+#define CX_SFMT(s) (int) (s).length, (s).ptr
+/** Format specifier for a UCX string */
+#define CX_PRIstr ".*s"
 /**
 * The maximum length of the "needle" in cx_strstr() that can use SBO.
 */
 cx_attr_export
 /**
 * Wraps a mutable string that must be zero-terminated.
 *
 * The length is implicitly inferred by using a call to @c strlen().
 *
+* When @c NULL is passed, the length will be set to zero.
+*
 * @note the wrapped string will share the specified pointer to the string.
 * If you do want a copy, use cx_strdup() on the return value of this function.
 *
 * If you need to wrap a constant string, use cx_str().
 *
 * @param cstring the string to wrap, must be zero-terminated
 * @return the wrapped string
 *
 * @see cx_mutstrn()
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_cstr_arg(1)
 cx_attr_export
 cxmutstr cx_mutstr(char *cstring);
 /**
 * Wraps a string that must be zero-terminated.
 *
 * The length is implicitly inferred by using a call to @c strlen().
 *
+* When @c NULL is passed, the length will be set to zero.
+*
 * @note the wrapped string will share the specified pointer to the string.
 * If you do want a copy, use cx_strdup() on the return value of this function.
 *
 * If you need to wrap a non-constant string, use cx_mutstr().
 *
 * @param cstring the string to wrap, must be zero-terminated
 * @return the wrapped string
 *
 * @see cx_strn()
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_cstr_arg(1)
 cx_attr_export
 cxstring cx_str(const char *cstring);
 return cx_strn(str.ptr, str.length);
 }
 cx_attr_nodiscard
 static inline cxstring cx_strcast(cxstring str) {
 return str;
+}
+cx_attr_nodiscard
+static inline cxstring cx_strcast(const char *str) {
+return cx_str(str);
 }
 extern "C" {
 #else
 /**
 * Internal function, do not use.
 * @see cx_strcast()
 */
 cx_attr_nodiscard
 static inline cxstring cx_strcast_c(cxstring str) {
 return str;
+}
+/**
+* Internal function, do not use.
+* @param str
+* @return
+* @see cx_strcast()
+*/
+cx_attr_nodiscard
+static inline cxstring cx_strcast_z(const char *str) {
+return cx_str(str);
 }
 /**
 * Casts a mutable string to an immutable string.
 *
 * @param str (@c cxstring or @c cxmutstr) the string to cast
 * @return (@c cxstring) an immutable copy of the string pointer
 */
 #define cx_strcast(str) _Generic((str), \
 cxmutstr: cx_strcast_m, \
-cxstring: cx_strcast_c) \
+cxstring: cx_strcast_c, \
-(str)
+const char*: cx_strcast_z, \
+char *: cx_strcast_z) (str)
 #endif
 /**
-* Passes the pointer in this string to @c free().
+* Passes the pointer in this string to the cxDefaultAllocator's @c free() function.
 *
 * The pointer in the struct is set to @c NULL and the length is set to zero
 * which means that this function protects you against double-free.
 *
 * @note There is no implementation for cxstring, because it is unlikely that
 cx_attr_export
 void cx_strfree_a(
 const CxAllocator *alloc,
 cxmutstr *str
 );
+/**
+* Copies a string.
+*
+* The memory in the @p dest structure is either allocated or re-allocated to fit the entire
+* source string, including a zero-terminator.
+*
+* The string in @p dest is guaranteed to be zero-terminated, regardless of whether @p src is.
+*
+* @param alloc the allocator
+* @param dest a pointer to the structure where to copy the contents to
+* @param src the source string
+*
+* @retval zero success
+* @retval non-zero if re-allocation failed
+*/
+cx_attr_nonnull_arg(1)
+cx_attr_export
+int cx_strcpy_a(
+const CxAllocator *alloc,
+cxmutstr *dest,
+cxstring src
+);
+/**
+* Copies a string.
+*
+* The memory in the @p dest structure is either allocated or re-allocated to fit the entire
+* source string, including a zero-terminator.
+*
+* The string in @p dest is guaranteed to be zero-terminated, regardless of whether @p src is.
+*
+* @param dest (@c cxmutstr*) a pointer to the structure where to copy the contents to
+* @param src (@c cxstring) the source string
+*
+* @retval zero success
+* @retval non-zero if re-allocation failed
+*/
+#define cx_strcpy(dest, src) cx_strcpy_a(cxDefaultAllocator, dest, src)
 /**
 * Returns the accumulated length of all specified strings.
 *
 * If this sum overflows, errno is set to EOVERFLOW.
 cx_strcat_ma(alloc, cx_mutstrn(NULL, 0), count, __VA_ARGS__)
 /**
 * Concatenates strings and returns a new string.
 *
-* The resulting string will be allocated by standard @c malloc().
+* The resulting string will be allocated by the cxDefaultAllocator.
 * So developers @em must pass the return value to cx_strfree() eventually.
 *
 * If memory allocation fails, the pointer in the returned string will
 * be @c NULL and @c errno might be set.
 *
 cx_strcat_ma(cxDefaultAllocator, cx_mutstrn(NULL, 0), count, __VA_ARGS__)
 /**
 * Concatenates strings.
 *
-* The resulting string will be allocated by standard @c malloc().
+* The resulting string will be allocated by the cxDefaultAllocator.
 * So developers @em must pass the return value to cx_strfree() eventually.
 *
 * If @p str already contains a string, the memory will be reallocated and
 * the other strings are appended. Otherwise, new memory is allocated.
 *
 cx_strdup_a_((allocator), cx_strcast(string))
 /**
 * Creates a duplicate of the specified string.
 *
-* The new string will contain a copy allocated by standard
+* The new string will contain a copy allocated by the cxDefaultAllocator.
-* @c malloc(). So developers @em must pass the return value to cx_strfree().
+* So developers @em must pass the return value to cx_strfree().
 *
 * @note The returned string is guaranteed to be zero-terminated.
 *
 * @param string the string to duplicate
 * @return (@c cxmutstr) a duplicate of the string
 /**
 * Replaces a string with another string.
 *
 * Replaces at most @p replmax occurrences.
 *
-* The returned string will be allocated by @c malloc() and is guaranteed
+* The returned string will be allocated by the cxDefaultAllocator and is guaranteed
 * to be zero-terminated.
 *
 * If allocation fails, or the input string is empty,
 * the returned string will be empty.
 *
 cx_strreplacen_a(allocator, str, search, replacement, SIZE_MAX)
 /**
 * Replaces a string with another string.
 *
-* The returned string will be allocated by @c malloc() and is guaranteed
+* The returned string will be allocated by the cxDefaultAllocator and is guaranteed
 * to be zero-terminated.
 *
 * If allocation fails, or the input string is empty,
 * the returned string will be empty.
 *

Mercurial > hg > dav / file comparison

comparison: ucx/cx/string.h

ucx/cx/string.h