--- name: "String.h" section: "3" platform: "linux" package: "libzycore-doc" version: "1.5.2-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/String.h" --- # String.h(3) ## NAME include/Zycore/String.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ ### Classes struct **ZyanString\_**\ struct **ZyanStringView\_**\ ### Macros \#define **ZYAN\_STRING\_MIN\_CAPACITY** 32\ \#define **ZYAN\_STRING\_DEFAULT\_GROWTH\_FACTOR** 2\ \#define **ZYAN\_STRING\_DEFAULT\_SHRINK\_THRESHOLD** 4\ \#define **ZYAN\_STRING\_HAS\_FIXED\_CAPACITY** 0x01\ \#define **ZYAN\_STRING\_INITIALIZER**\ \#define **ZYAN\_STRING\_TO\_VIEW**(string) (const **ZyanStringView**\*)(string)\ \#define **ZYAN\_DEFINE\_STRING\_VIEW**(string)\ ### Typedefs typedef ZyanU8 **ZyanStringFlags**\ typedef struct **ZyanString\_** **ZyanString**\ typedef struct **ZyanStringView\_** **ZyanStringView**\ ### Functions **ZYCORE\_EXPORT** **ZYAN\_REQUIRES\_LIBC** **ZyanStatus** **ZyanStringInit** (**ZyanString** \*string, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInitEx** (**ZyanString** \*string, ZyanUSize capacity, **ZyanAllocator** \*allocator, ZyanU8 growth\_factor, ZyanU8 shrink\_threshold)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInitCustomBuffer** (**ZyanString** \*string, char \*buffer, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringDestroy** (**ZyanString** \*string)\ **ZYCORE\_EXPORT** **ZYAN\_REQUIRES\_LIBC** **ZyanStatus** **ZyanStringDuplicate** (**ZyanString** \*destination, const **ZyanStringView** \*source, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringDuplicateEx** (**ZyanString** \*destination, const **ZyanStringView** \*source, ZyanUSize capacity, **ZyanAllocator** \*allocator, ZyanU8 growth\_factor, ZyanU8 shrink\_threshold)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringDuplicateCustomBuffer** (**ZyanString** \*destination, const **ZyanStringView** \*source, char \*buffer, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZYAN\_REQUIRES\_LIBC** **ZyanStatus** **ZyanStringConcat** (**ZyanString** \*destination, const **ZyanStringView** \*s1, const **ZyanStringView** \*s2, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringConcatEx** (**ZyanString** \*destination, const **ZyanStringView** \*s1, const **ZyanStringView** \*s2, ZyanUSize capacity, **ZyanAllocator** \*allocator, ZyanU8 growth\_factor, ZyanU8 shrink\_threshold)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringConcatCustomBuffer** (**ZyanString** \*destination, const **ZyanStringView** \*s1, const **ZyanStringView** \*s2, char \*buffer, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringViewInsideView** (**ZyanStringView** \*view, const **ZyanStringView** \*source)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringViewInsideViewEx** (**ZyanStringView** \*view, const **ZyanStringView** \*source, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringViewInsideBuffer** (**ZyanStringView** \*view, const char \*string)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringViewInsideBufferEx** (**ZyanStringView** \*view, const char \*buffer, ZyanUSize length)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringViewGetSize** (const **ZyanStringView** \*view, ZyanUSize \*size)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringViewGetData** (const **ZyanStringView** \*view, const char \*\*buffer)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringGetChar** (const **ZyanStringView** \*string, ZyanUSize index, char \*value)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringGetCharMutable** (**ZyanString** \*string, ZyanUSize index, char \*\*value)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringSetChar** (**ZyanString** \*string, ZyanUSize index, char value)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsert** (**ZyanString** \*destination, ZyanUSize index, const **ZyanStringView** \*source)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsertEx** (**ZyanString** \*destination, ZyanUSize destination\_index, const **ZyanStringView** \*source, ZyanUSize source\_index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringAppend** (**ZyanString** \*destination, const **ZyanStringView** \*source)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringAppendEx** (**ZyanString** \*destination, const **ZyanStringView** \*source, ZyanUSize source\_index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringDelete** (**ZyanString** \*string, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringTruncate** (**ZyanString** \*string, ZyanUSize index)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringClear** (**ZyanString** \*string)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringLPos** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringLPosEx** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringLPosI** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringLPosIEx** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringRPos** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringRPosEx** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringRPosI** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringRPosIEx** (const **ZyanStringView** \*haystack, const **ZyanStringView** \*needle, ZyanISize \*found\_index, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringCompare** (const **ZyanStringView** \*s1, const **ZyanStringView** \*s2, ZyanI32 \*result)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringCompareI** (const **ZyanStringView** \*s1, const **ZyanStringView** \*s2, ZyanI32 \*result)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringToLowerCase** (**ZyanString** \*string)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringToLowerCaseEx** (**ZyanString** \*string, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringToUpperCase** (**ZyanString** \*string)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringToUpperCaseEx** (**ZyanString** \*string, ZyanUSize index, ZyanUSize count)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringResize** (**ZyanString** \*string, ZyanUSize size)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringReserve** (**ZyanString** \*string, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringShrinkToFit** (**ZyanString** \*string)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringGetCapacity** (const **ZyanString** \*string, ZyanUSize \*capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringGetSize** (const **ZyanString** \*string, ZyanUSize \*size)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringGetData** (const **ZyanString** \*string, const char \*\*value)\ ## Detailed Description Implements a string type. ## Macro Definition Documentation ### #define ZYAN\_DEFINE\_STRING\_VIEW(string) **Value:**.PP ``` { \ /* string */ \ { \ /* flags */ 0, \ /* vector */ \ { \ /* allocator */ ZYAN_NULL, \ /* growth_factor */ 1, \ /* shrink_threshold */ 0, \ /* size */ sizeof(string), \ /* capacity */ sizeof(string), \ /* element_size */ sizeof(char), \ /* destructor */ ZYAN_NULL, \ /* data */ (char*)(string) \ } \ } \ } ``` Defines a `ZyanStringView` struct that provides a view into a static C-style string. **Parameters** *string* The C-style string. ### #define ZYAN\_STRING\_DEFAULT\_GROWTH\_FACTOR 2 The default growth factor for all string instances. ### #define ZYAN\_STRING\_DEFAULT\_SHRINK\_THRESHOLD 4 The default shrink threshold for all string instances. ### #define ZYAN\_STRING\_HAS\_FIXED\_CAPACITY 0x01 The string uses a custom user-defined buffer with a fixed capacity. ### #define ZYAN\_STRING\_INITIALIZER **Value:**.PP ``` { \ /* flags */ 0, \ /* vector */ ZYAN_VECTOR_INITIALIZER \ } ``` Defines an uninitialized `ZyanString` instance. ### #define ZYAN\_STRING\_MIN\_CAPACITY 32 The initial minimum capacity (number of characters) for all dynamically allocated string instances - not including the terminating '\\0'-character. ### #define ZYAN\_STRING\_TO\_VIEW(string) (const ZyanStringView\*)(string) Casts a `ZyanString` pointer to a constant `ZyanStringView` pointer. ## Typedef Documentation ### typedef struct ZyanString\_ ZyanString Defines the `ZyanString` struct. The `ZyanString` type is implemented as a size-prefixed string - which allows for a lot of performance optimizations. Nevertheless null-termination is guaranteed at all times to provide maximum compatibility with default C-style strings (use `ZyanStringGetData` to access the C-style string). All fields in this struct should be considered as 'private'. Any changes may lead to unexpected behavior. ### typedef ZyanU8 ZyanStringFlags Defines the `ZyanStringFlags` data-type. ### typedef struct ZyanStringView\_ ZyanStringView Defines the `ZyanStringView` struct. The `ZyanStringView` type provides a view inside a string (`ZyanString` instances, null- terminated C-style strings, or even not-null-terminated custom strings). A view is immutable by design and can't be directly converted to a C-style string. Views might become invalid (e.g. pointing to invalid memory), if the underlying string gets destroyed or resized. The `ZYAN_STRING_TO_VIEW` macro can be used to cast a `ZyanString` to a `ZyanStringView` pointer without any runtime overhead. Casting a view to a normal string is not supported and will lead to unexpected behavior (use `ZyanStringDuplicate` to create a deep-copy instead). All fields in this struct should be considered as 'private'. Any changes may lead to unexpected behavior. ## Function Documentation ### ZYCORE\_EXPORT ZyanStatus ZyanStringAppend (ZyanString \* destination, const ZyanStringView \* source) Appends the content of the source string to the end of the destination string. **Parameters** *destination* The destination string. \ *source* The source string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringAppendEx (ZyanString \* destination, const ZyanStringView \* source, ZyanUSize source\_index, ZyanUSize count) Appends `count` characters of the source string to the end of the destination string. **Parameters** *destination* The destination string. \ *source* The source string. \ *source\_index* The index of the first character to be appended from the source string. \ *count* The number of chars to append from the source string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringClear (ZyanString \* string) Erases the given string. **Parameters** *string* A pointer to the `ZyanString` instance. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringCompare (const ZyanStringView \* s1, const ZyanStringView \* s2, ZyanI32 \* result) Compares two strings. **Parameters** *s1* The first string \ *s2* The second string. \ *result* Receives the comparison result. ``` Values: - `result < 0` -> The first character that does not match has a lower value in `s1` than in `s2`. - `result == 0` -> The contents of both strings are equal. - `result > 0` -> The first character that does not match has a greater value in `s1` than in `s2`. ``` **Returns** `ZYAN_STATUS_TRUE`, if the strings are equal, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. ### ZYCORE\_EXPORT ZyanStatus ZyanStringCompareI (const ZyanStringView \* s1, const ZyanStringView \* s2, ZyanI32 \* result) Performs a case-insensitive comparison of two strings. **Parameters** *s1* The first string \ *s2* The second string. \ *result* Receives the comparison result. ``` Values: - `result < 0` -> The first character that does not match has a lower value in `s1` than in `s2`. - `result == 0` -> The contents of both strings are equal. - `result > 0` -> The first character that does not match has a greater value in `s1` than in `s2`. ``` **Returns** `ZYAN_STATUS_TRUE`, if the strings are equal, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. ### ZYCORE\_EXPORT ZYAN\_REQUIRES\_LIBC ZyanStatus ZyanStringConcat (ZyanString \* destination, const ZyanStringView \* s1, const ZyanStringView \* s2, ZyanUSize capacity) Initializes a new `ZyanString` instance by concatenating two existing strings. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanString` instance. ``` This function will fail, if the destination `ZyanString` instance equals one of the source strings. ``` *s1* A pointer to the first source string. \ *s2* A pointer to the second source string. \ *capacity* The initial capacity (number of characters). ``` This value is automatically adjusted to the combined size of the source strings, if a smaller value was passed. ``` **Returns** A zyan status code. The behavior of this function is undefined, if `s1` or `s2` are views into the `destination` string or `destination` points to an already initialized `ZyanString` instance. The memory for the string is dynamically allocated by the default allocator using the default growth factor and the default shrink threshold. The allocated buffer will be at least one character larger than the given `capacity`, to reserve space for the terminating '\\0'. Finalization with `ZyanStringDestroy` is required for all strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringConcatCustomBuffer (ZyanString \* destination, const ZyanStringView \* s1, const ZyanStringView \* s2, char \* buffer, ZyanUSize capacity) Initializes a new `ZyanString` instance by concatenating two existing strings and configures it to use a custom user defined buffer with a fixed size. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanString` instance. ``` This function will fail, if the destination `ZyanString` instance equals one of the source strings. ``` *s1* A pointer to the first source string. \ *s2* A pointer to the second source string. \ *buffer* A pointer to the buffer that is used as storage for the string. \ *capacity* The maximum capacity (number of characters) of the buffer. ``` This function will fail, if the capacity of the buffer is less or equal to the combined size of the source strings. ``` **Returns** A zyan status code. The behavior of this function is undefined, if `s1` or `s2` are views into the `destination` string or `destination` points to an already initialized `ZyanString` instance. Finalization is not required for strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringConcatEx (ZyanString \* destination, const ZyanStringView \* s1, const ZyanStringView \* s2, ZyanUSize capacity, ZyanAllocator \* allocator, ZyanU8 growth\_factor, ZyanU8 shrink\_threshold) Initializes a new `ZyanString` instance by concatenating two existing strings and sets a custom `allocator` and memory allocation/deallocation parameters. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanString` instance. ``` This function will fail, if the destination `ZyanString` instance equals one of the source strings. ``` *s1* A pointer to the first source string. \ *s2* A pointer to the second source string. \ *capacity* The initial capacity (number of characters). ``` This value is automatically adjusted to the combined size of the source strings, if a smaller value was passed. ``` *allocator* A pointer to a `ZyanAllocator` instance. \ *growth\_factor* The growth factor. \ *shrink\_threshold* The shrink threshold. **Returns** A zyan status code. The behavior of this function is undefined, if `s1` or `s2` are views into the `destination` string or `destination` points to an already initialized `ZyanString` instance. A growth factor of `1` disables overallocation and a shrink threshold of `0` disables dynamic shrinking. The allocated buffer will be at least one character larger than the given `capacity`, to reserve space for the terminating '\\0'. Finalization with `ZyanStringDestroy` is required for all strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringDelete (ZyanString \* string, ZyanUSize index, ZyanUSize count) Deletes characters from the given string, starting at `index`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The index of the first character to delete. \ *count* The number of characters to delete. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringDestroy (ZyanString \* string) Destroys the given `ZyanString` instance. **Parameters** *string* A pointer to the `ZyanString` instance. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZYAN\_REQUIRES\_LIBC ZyanStatus ZyanStringDuplicate (ZyanString \* destination, const ZyanStringView \* source, ZyanUSize capacity) Initializes a new `ZyanString` instance by duplicating an existing string. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanString` instance. \ *source* A pointer to the source string. \ *capacity* The initial capacity (number of characters). ``` This value is automatically adjusted to the size of the source string, if a smaller value was passed. ``` **Returns** A zyan status code. The behavior of this function is undefined, if `source` is a view into the `destination` string or `destination` points to an already initialized `ZyanString` instance. The memory for the string is dynamically allocated by the default allocator using the default growth factor and the default shrink threshold. The allocated buffer will be at least one character larger than the given `capacity`, to reserve space for the terminating '\\0'. Finalization with `ZyanStringDestroy` is required for all strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringDuplicateCustomBuffer (ZyanString \* destination, const ZyanStringView \* source, char \* buffer, ZyanUSize capacity) Initializes a new `ZyanString` instance by duplicating an existing string and configures it to use a custom user defined buffer with a fixed size. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanString` instance. \ *source* A pointer to the source string. \ *buffer* A pointer to the buffer that is used as storage for the string. \ *capacity* The maximum capacity (number of characters) of the buffer, including the terminating '\\0'. This function will fail, if the capacity of the buffer is less or equal to the size of the source string. **Returns** A zyan status code. The behavior of this function is undefined, if `source` is a view into the `destination` string or `destination` points to an already initialized `ZyanString` instance. Finalization is not required for strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringDuplicateEx (ZyanString \* destination, const ZyanStringView \* source, ZyanUSize capacity, ZyanAllocator \* allocator, ZyanU8 growth\_factor, ZyanU8 shrink\_threshold) Initializes a new `ZyanString` instance by duplicating an existing string and sets a custom `allocator` and memory allocation/deallocation parameters. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanString` instance. \ *source* A pointer to the source string. \ *capacity* The initial capacity (number of characters). ``` This value is automatically adjusted to the size of the source string, if a smaller value was passed. ``` *allocator* A pointer to a `ZyanAllocator` instance. \ *growth\_factor* The growth factor. \ *shrink\_threshold* The shrink threshold. **Returns** A zyan status code. The behavior of this function is undefined, if `source` is a view into the `destination` string or `destination` points to an already initialized `ZyanString` instance. A growth factor of `1` disables overallocation and a shrink threshold of `0` disables dynamic shrinking. The allocated buffer will be at least one character larger than the given `capacity`, to reserve space for the terminating '\\0'. Finalization with `ZyanStringDestroy` is required for all strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringGetCapacity (const ZyanString \* string, ZyanUSize \* capacity) Returns the current capacity of the string. **Parameters** *string* A pointer to the `ZyanString` instance. \ *capacity* Receives the size of the string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringGetChar (const ZyanStringView \* string, ZyanUSize index, char \* value) Returns the character at the given `index`. **Parameters** *string* A pointer to the `ZyanStringView` instance. \ *index* The character index. \ *value* Receives the desired character of the string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringGetCharMutable (ZyanString \* string, ZyanUSize index, char \*\* value) Returns a pointer to the character at the given `index`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The character index. \ *value* Receives a pointer to the desired character in the string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringGetData (const ZyanString \* string, const char \*\* value) Returns the C-style string of the given `ZyanString` instance. **Parameters** *string* A pointer to the `ZyanString` instance. \ *value* Receives a pointer to the C-style string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringGetSize (const ZyanString \* string, ZyanUSize \* size) Returns the current size (number of characters) of the string (excluding the terminating zero character). **Parameters** *string* A pointer to the `ZyanString` instance. \ *size* Receives the size (number of characters) of the string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZYAN\_REQUIRES\_LIBC ZyanStatus ZyanStringInit (ZyanString \* string, ZyanUSize capacity) Initializes the given `ZyanString` instance. **Parameters** *string* A pointer to the `ZyanString` instance. \ *capacity* The initial capacity (number of characters). **Returns** A zyan status code. The memory for the string is dynamically allocated by the default allocator using the default growth factor and the default shrink threshold. The allocated buffer will be at least one character larger than the given `capacity`, to reserve space for the terminating '\\0'. Finalization with `ZyanStringDestroy` is required for all strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInitCustomBuffer (ZyanString \* string, char \* buffer, ZyanUSize capacity) Initializes the given `ZyanString` instance and configures it to use a custom user defined buffer with a fixed size. **Parameters** *string* A pointer to the `ZyanString` instance. \ *buffer* A pointer to the buffer that is used as storage for the string. \ *capacity* The maximum capacity (number of characters) of the buffer, including the terminating '\\0'. **Returns** A zyan status code. Finalization is not required for strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInitEx (ZyanString \* string, ZyanUSize capacity, ZyanAllocator \* allocator, ZyanU8 growth\_factor, ZyanU8 shrink\_threshold) Initializes the given `ZyanString` instance and sets a custom `allocator` and memory allocation/deallocation parameters. **Parameters** *string* A pointer to the `ZyanString` instance. \ *capacity* The initial capacity (number of characters). \ *allocator* A pointer to a `ZyanAllocator` instance. \ *growth\_factor* The growth factor. \ *shrink\_threshold* The shrink threshold. **Returns** A zyan status code. A growth factor of `1` disables overallocation and a shrink threshold of `0` disables dynamic shrinking. The allocated buffer will be at least one character larger than the given `capacity`, to reserve space for the terminating '\\0'. Finalization with `ZyanStringDestroy` is required for all strings created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsert (ZyanString \* destination, ZyanUSize index, const ZyanStringView \* source) Inserts the content of the source string in the destination string at the given `index`. **Parameters** *destination* The destination string. \ *index* The insert index. \ *source* The source string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsertEx (ZyanString \* destination, ZyanUSize destination\_index, const ZyanStringView \* source, ZyanUSize source\_index, ZyanUSize count) Inserts `count` characters of the source string in the destination string at the given `index`. **Parameters** *destination* The destination string. \ *destination\_index* The insert index. \ *source* The source string. \ *source\_index* The index of the first character to be inserted from the source string. \ *count* The number of chars to insert from the source string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringLPos (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index) Searches for the first occurrence of `needle` in the given `haystack` starting from the left. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occured. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringLPosEx (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index, ZyanUSize index, ZyanUSize count) Searches for the first occurrence of `needle` in the given `haystack` starting from the left. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. \ *index* The start index. \ *count* The maximum number of characters to iterate, beginning from the start `index`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occured. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringLPosI (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index) Performs a case-insensitive search for the first occurrence of `needle` in the given `haystack` starting from the left. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occured. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringLPosIEx (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index, ZyanUSize index, ZyanUSize count) Performs a case-insensitive search for the first occurrence of `needle` in the given `haystack` starting from the left. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. \ *index* The start index. \ *count* The maximum number of characters to iterate, beginning from the start `index`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringReserve (ZyanString \* string, ZyanUSize capacity) Changes the capacity of the given `ZyanString` instance. **Parameters** *string* A pointer to the `ZyanString` instance. \ *capacity* The new minimum capacity of the string. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringResize (ZyanString \* string, ZyanUSize size) Resizes the given `ZyanString` instance. **Parameters** *string* A pointer to the `ZyanString` instance. \ *size* The new size of the string. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringRPos (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index) Searches for the first occurrence of `needle` in the given `haystack` starting from the right. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringRPosEx (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index, ZyanUSize index, ZyanUSize count) Searches for the first occurrence of `needle` in the given `haystack` starting from the right. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. \ *index* The start index. \ *count* The maximum number of characters to iterate, beginning from the start `index`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringRPosI (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index) Performs a case-insensitive search for the first occurrence of `needle` in the given `haystack` starting from the right. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringRPosIEx (const ZyanStringView \* haystack, const ZyanStringView \* needle, ZyanISize \* found\_index, ZyanUSize index, ZyanUSize count) Performs a case-insensitive search for the first occurrence of `needle` in the given `haystack` starting from the right. **Parameters** *haystack* The string to search in. \ *needle* The sub-string to search for. \ *found\_index* A pointer to a variable that receives the index of the first occurrence of `needle`. \ *index* The start index. \ *count* The maximum number of characters to iterate, beginning from the start `index`. **Returns** `ZYAN_STATUS_TRUE`, if the needle was found, `ZYAN_STATUS_FALSE`, if not, or another zyan status code, if an error occurred. The `found_index` is set to `-1`, if the needle was not found. ### ZYCORE\_EXPORT ZyanStatus ZyanStringSetChar (ZyanString \* string, ZyanUSize index, char value) Assigns a new value to the character at the given `index`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The character index. \ *value* The character to assign. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringShrinkToFit (ZyanString \* string) Shrinks the capacity of the given string to match it's size. **Parameters** *string* A pointer to the `ZyanString` instance. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringToLowerCase (ZyanString \* string) Converts the given string to lowercase letters. **Parameters** *string* A pointer to the `ZyanString` instance. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringToLowerCaseEx (ZyanString \* string, ZyanUSize index, ZyanUSize count) Converts `count` characters of the given string to lowercase letters. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The start index. \ *count* The number of characters to convert, beginning from the start `index`. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringToUpperCase (ZyanString \* string) Converts the given string to uppercase letters. **Parameters** *string* A pointer to the `ZyanString` instance. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringToUpperCaseEx (ZyanString \* string, ZyanUSize index, ZyanUSize count) Converts `count` characters of the given string to uppercase letters. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The start index. \ *count* The number of characters to convert, beginning from the start `index`. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringTruncate (ZyanString \* string, ZyanUSize index) Deletes all remaining characters from the given string, starting at `index`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The index of the first character to delete. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringViewGetData (const ZyanStringView \* view, const char \*\* buffer) Returns the C-style string of the given `ZyanString` instance. **Warning** The string is not guaranteed to be null terminated! **Parameters** *view* A pointer to the `ZyanStringView` instance. \ *buffer* Receives a pointer to the C-style string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringViewGetSize (const ZyanStringView \* view, ZyanUSize \* size) Returns the size (number of characters) of the view. **Parameters** *view* A pointer to the `ZyanStringView` instance. \ *size* Receives the size (number of characters) of the view. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringViewInsideBuffer (ZyanStringView \* view, const char \* string) Returns a view inside a null-terminated C-style string. **Parameters** *view* A pointer to the `ZyanStringView` instance. \ *string* The C-style string. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringViewInsideBufferEx (ZyanStringView \* view, const char \* buffer, ZyanUSize length) Returns a view inside a character buffer with custom length. **Parameters** *view* A pointer to the `ZyanStringView` instance. \ *buffer* A pointer to the buffer containing the string characters. \ *length* The length of the string (number of characters). **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanStringViewInsideView (ZyanStringView \* view, const ZyanStringView \* source) Returns a view inside an existing view/string. **Parameters** *view* A pointer to the `ZyanStringView` instance. \ *source* A pointer to the source string. **Returns** A zyan status code. The `ZYAN_STRING_TO_VEW` macro can be used to pass any `ZyanString` instance as value for the `source` string. ### ZYCORE\_EXPORT ZyanStatus ZyanStringViewInsideViewEx (ZyanStringView \* view, const ZyanStringView \* source, ZyanUSize index, ZyanUSize count) Returns a view inside an existing view/string starting from the given `index`. **Parameters** *view* A pointer to the `ZyanStringView` instance. \ *source* A pointer to the source string. \ *index* The start index. \ *count* The number of characters. **Returns** A zyan status code. The `ZYAN_STRING_TO_VEW` macro can be used to pass any `ZyanString` instance as value for the `source` string. ## Author Generated automatically by Doxygen for Zycore from the source code.