diff options
author | David Robillard <d@drobilla.net> | 2022-10-23 12:58:06 -0400 |
---|---|---|
committer | David Robillard <d@drobilla.net> | 2022-10-23 13:42:13 -0400 |
commit | f95a698b94069ed03f6a8f2d0f7eb089d66c91ef (patch) | |
tree | 92da0fe8ece8a1890bf23fe67a38eb95556d03d8 /include/zix/string_view.h | |
parent | e883ea50dd1154294e21e946e391dd38e04d6527 (diff) | |
download | zix-f95a698b94069ed03f6a8f2d0f7eb089d66c91ef.tar.gz zix-f95a698b94069ed03f6a8f2d0f7eb089d66c91ef.tar.bz2 zix-f95a698b94069ed03f6a8f2d0f7eb089d66c91ef.zip |
Add string view API
Diffstat (limited to 'include/zix/string_view.h')
-rw-r--r-- | include/zix/string_view.h | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/include/zix/string_view.h b/include/zix/string_view.h new file mode 100644 index 0000000..f4cd6c2 --- /dev/null +++ b/include/zix/string_view.h @@ -0,0 +1,107 @@ +// Copyright 2011-2021 David Robillard <d@drobilla.net> +// SPDX-License-Identifier: ISC + +#ifndef ZIX_STRING_VIEW_H +#define ZIX_STRING_VIEW_H + +#include "zix/allocator.h" +#include "zix/attributes.h" + +#include <stddef.h> +#include <string.h> + +ZIX_BEGIN_DECLS + +/** + @defgroup zix_string_view String View + @ingroup zix_utilities + @{ +*/ + +/** + An immutable slice of a string. + + This type is used for many string parameters, to allow referring to slices + of strings in-place and to avoid redundant string measurement. +*/ +typedef struct { + const char* ZIX_NONNULL data; ///< Pointer to the first character + size_t length; ///< Length of string in bytes +} ZixStringView; + +/// Return a view of an empty string +ZIX_ALWAYS_INLINE_FUNC +ZIX_CONST_FUNC +static inline ZixStringView +zix_empty_string(void) +{ + const ZixStringView view = {"", 0U}; + return view; +} + +/** + Return a view of a substring, or a premeasured string. + + This makes either a view of a slice of a string (which may not be null + terminated), or a view of a string that has already been measured. This is + faster than zix_string() for dynamic strings since it does not call + `strlen`, so should be used when the length of the string is already known. + + @param str Pointer to the start of the substring. + + @param len Length of the substring in bytes, not including the trailing null + terminator if present. +*/ +ZIX_ALWAYS_INLINE_FUNC +ZIX_CONST_FUNC +static inline ZixStringView +zix_substring(const char* const ZIX_NONNULL str, const size_t len) +{ + const ZixStringView view = {str, len}; + return view; +} + +/** + Return a view of an entire string by measuring it. + + This makes a view of the given string by measuring it with `strlen`. + + @param str Pointer to the start of a null-terminated C string, or null. +*/ +ZIX_ALWAYS_INLINE_FUNC +ZIX_PURE_FUNC +static inline ZixStringView +zix_string(const char* const ZIX_NONNULL str) +{ + const ZixStringView view = {str, strlen(str)}; + return view; +} + +/** + Return a view of an entire string by measuring it. + + This makes a view of the given string by measuring it with `strlen`. + + @param str Pointer to the start of a null-terminated C string, or null. +*/ +ZIX_PURE_FUNC +static inline ZixStringView +zix_optional_string(const char* const ZIX_NULLABLE str) +{ + return str ? zix_string(str) : zix_empty_string(); +} + +/** + Copy a string view into a newly allocated null-terminated string. +*/ +ZIX_API +char* ZIX_ALLOCATED +zix_string_view_copy(ZixAllocator* ZIX_NULLABLE allocator, ZixStringView view); + +/** + @} +*/ + +ZIX_END_DECLS + +#endif // ZIX_STRING_VIEW_H |