Scroll to navigation

include/Zycore/String.h(3) Library Functions Manual include/Zycore/String.h(3)

NAME

include/Zycore/String.h

SYNOPSIS

#include <Zycore/Allocator.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>
#include <Zycore/Vector.h>

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.

Version 1.5.1.0 Zycore