Zycore 1.5.1.0
Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
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)   (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

◆ 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
stringThe 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 \
}
#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)    (const ZyanStringView*)(string)

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

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
destinationThe destination string.
sourceThe 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
destinationThe destination string.
sourceThe source string.
source_indexThe index of the first character to be appended from the source string.
countThe 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
stringA 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
s1The first string
s2The second string.
resultReceives 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
s1The first string
s2The second string.
resultReceives 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
destinationA pointer to the (uninitialized) destination ZyanString instance.
                 This function will fail, if the destination `ZyanString` instance equals
                 one of the source strings.
s1A pointer to the first source string.
s2A pointer to the second source string.
capacityThe 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
destinationA pointer to the (uninitialized) destination ZyanString instance.
                 This function will fail, if the destination `ZyanString` instance equals
                 one of the source strings.
s1A pointer to the first source string.
s2A pointer to the second source string.
bufferA pointer to the buffer that is used as storage for the string.
capacityThe 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
destinationA pointer to the (uninitialized) destination ZyanString instance.
                         This function will fail, if the destination `ZyanString` instance
                         equals one of the source strings.
s1A pointer to the first source string.
s2A pointer to the second source string.
capacityThe initial capacity (number of characters).
                         This value is automatically adjusted to the combined size of the
                         source strings, if a smaller value was passed.
allocatorA pointer to a ZyanAllocator instance.
growth_factorThe growth factor.
shrink_thresholdThe 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
stringA pointer to the ZyanString instance.
indexThe index of the first character to delete.
countThe number of characters to delete.
Returns
A zyan status code.

◆ ZyanStringDestroy()

ZYCORE_EXPORT ZyanStatus ZyanStringDestroy ( ZyanString string)

Destroys the given ZyanString instance.

Parameters
stringA 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
destinationA pointer to the (uninitialized) destination ZyanString instance.
sourceA pointer to the source string.
capacityThe 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
destinationA pointer to the (uninitialized) destination ZyanString instance.
sourceA pointer to the source string.
bufferA pointer to the buffer that is used as storage for the string.
capacityThe 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
destinationA pointer to the (uninitialized) destination ZyanString instance.
sourceA pointer to the source string.
capacityThe initial capacity (number of characters).
                         This value is automatically adjusted to the size of the source
                         string, if a smaller value was passed.
allocatorA pointer to a ZyanAllocator instance.
growth_factorThe growth factor.
shrink_thresholdThe 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
stringA pointer to the ZyanString instance.
capacityReceives 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
stringA pointer to the ZyanStringView instance.
indexThe character index.
valueReceives 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
stringA pointer to the ZyanString instance.
indexThe character index.
valueReceives 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
stringA pointer to the ZyanString instance.
valueReceives 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
stringA pointer to the ZyanString instance.
sizeReceives 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
stringA pointer to the ZyanString instance.
capacityThe 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
stringA pointer to the ZyanString instance.
bufferA pointer to the buffer that is used as storage for the string.
capacityThe 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
stringA pointer to the ZyanString instance.
capacityThe initial capacity (number of characters).
allocatorA pointer to a ZyanAllocator instance.
growth_factorThe growth factor.
shrink_thresholdThe 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
destinationThe destination string.
indexThe insert index.
sourceThe 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
destinationThe destination string.
destination_indexThe insert index.
sourceThe source string.
source_indexThe index of the first character to be inserted from the source string.
countThe 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA pointer to a variable that receives the index of the first occurrence of needle.
indexThe start index.
countThe 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA pointer to a variable that receives the index of the first occurrence of needle.
indexThe start index.
countThe 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
stringA pointer to the ZyanString instance.
capacityThe 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
stringA pointer to the ZyanString instance.
sizeThe 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA pointer to a variable that receives the index of the first occurrence of needle.
indexThe start index.
countThe 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA 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
haystackThe string to search in.
needleThe sub-string to search for.
found_indexA pointer to a variable that receives the index of the first occurrence of needle.
indexThe start index.
countThe 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
stringA pointer to the ZyanString instance.
indexThe character index.
valueThe 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
stringA 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
stringA 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
stringA pointer to the ZyanString instance.
indexThe start index.
countThe 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
stringA 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
stringA pointer to the ZyanString instance.
indexThe start index.
countThe 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
stringA pointer to the ZyanString instance.
indexThe 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
viewA pointer to the ZyanStringView instance.
bufferReceives 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
viewA pointer to the ZyanStringView instance.
sizeReceives 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
viewA pointer to the ZyanStringView instance.
stringThe 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
viewA pointer to the ZyanStringView instance.
bufferA pointer to the buffer containing the string characters.
lengthThe 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
viewA pointer to the ZyanStringView instance.
sourceA 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
viewA pointer to the ZyanStringView instance.
sourceA pointer to the source string.
indexThe start index.
countThe 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.