Loading...
Searching...
No Matches
String.h File Reference
`#include <Zycore/Allocator.h>`
`#include <Zycore/Status.h>`
`#include <Zycore/Types.h>`
`#include <Zycore/Vector.h>`
Include dependency graph for String.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## 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)
#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

## ZYAN_DEFINE_STRING_VIEW

#define ZYAN_DEFINE_STRING_VIEW | ( |  | string | ) |

Value:
{ \
/* 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.

## ZYAN_STRING_DEFAULT_GROWTH_FACTOR

#define ZYAN_STRING_DEFAULT_GROWTH_FACTOR 2

The default growth factor for all string instances.

## ZYAN_STRING_DEFAULT_SHRINK_THRESHOLD

#define ZYAN_STRING_DEFAULT_SHRINK_THRESHOLD 4

The default shrink threshold for all string instances.

## ZYAN_STRING_HAS_FIXED_CAPACITY

#define ZYAN_STRING_HAS_FIXED_CAPACITY 0x01

The string uses a custom user-defined buffer with a fixed capacity.

## ZYAN_STRING_INITIALIZER

#define ZYAN_STRING_INITIALIZER

Value:
{ \
/* flags */ 0, \
/* vector */ ZYAN_VECTOR_INITIALIZER \
}
ZYAN_VECTOR_INITIALIZER
#define ZYAN_VECTOR_INITIALIZER
Definition Vector.h:122

Defines an uninitialized ZyanString instance.

## ZYAN_STRING_MIN_CAPACITY

#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.

## ZYAN_STRING_TO_VIEW

#define ZYAN_STRING_TO_VIEW | ( |  | string | ) |

Value:
(const ZyanStringView*)(string)
ZyanStringView
struct ZyanStringView_ ZyanStringView

Casts a ZyanString pointer to a constant ZyanStringView pointer.

## Typedef Documentation

## ZyanString

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.

## ZyanStringFlags

typedef ZyanU8 ZyanStringFlags

Defines the ZyanStringFlags data-type.

## ZyanStringView

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

## ZyanStringAppend()

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.

## ZyanStringAppendEx()

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.

## ZyanStringClear()

ZYCORE_EXPORT ZyanStatus ZyanStringClear | ( | ZyanString * | string | ) |

Erases the given string.

Parameters

  string | A pointer to the ZyanString instance.

Returns
  A zyan status code.

## ZyanStringCompare()

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.

## ZyanStringCompareI()

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.

## ZyanStringConcat()

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.

## ZyanStringConcatCustomBuffer()

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.

## ZyanStringConcatEx()

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.

## ZyanStringDelete()

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.

## ZyanStringDestroy()

ZYCORE_EXPORT ZyanStatus ZyanStringDestroy | ( | ZyanString * | string | ) |

Destroys the given ZyanString instance.

Parameters

  string | A pointer to the ZyanString instance.

Returns
  A zyan status code.

## ZyanStringDuplicate()

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.

## ZyanStringDuplicateCustomBuffer()

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.

## ZyanStringDuplicateEx()

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.

## ZyanStringGetCapacity()

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.

## ZyanStringGetChar()

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.

## ZyanStringGetCharMutable()

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.

## ZyanStringGetData()

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.

## ZyanStringGetSize()

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.

## ZyanStringInit()

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.

## ZyanStringInitCustomBuffer()

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.

## ZyanStringInitEx()

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.

## ZyanStringInsert()

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.

## ZyanStringInsertEx()

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.

## ZyanStringLPos()

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.

## ZyanStringLPosEx()

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.

## ZyanStringLPosI()

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.

## ZyanStringLPosIEx()

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.

## ZyanStringReserve()

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.

## ZyanStringResize()

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.

## ZyanStringRPos()

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.

## ZyanStringRPosEx()

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.

## ZyanStringRPosI()

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.

## ZyanStringRPosIEx()

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.

## ZyanStringSetChar()

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.

## ZyanStringShrinkToFit()

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.

## ZyanStringToLowerCase()

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.

## ZyanStringToLowerCaseEx()

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.

## ZyanStringToUpperCase()

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.

## ZyanStringToUpperCaseEx()

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.

## ZyanStringTruncate()

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.

## ZyanStringViewGetData()

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.

## ZyanStringViewGetSize()

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.

## ZyanStringViewInsideBuffer()

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.

## ZyanStringViewInsideBufferEx()

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.

## ZyanStringViewInsideView()

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.

## ZyanStringViewInsideViewEx()

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.