| include/Zycore/String.h(3) | Library Functions Manual | include/Zycore/String.h(3) |
include/Zycore/String.h
#include <Zycore/Allocator.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>
#include <Zycore/Vector.h>
struct ZyanString_
struct ZyanStringView_
#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)
typedef ZyanU8 ZyanStringFlags
typedef struct ZyanString_ ZyanString
typedef struct ZyanStringView_ ZyanStringView
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)
Implements a string type.
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
The default growth factor for all string instances.
The default shrink threshold for all string instances.
The string uses a custom user-defined buffer with a fixed capacity.
Value:.PP
{ \
/* flags */ 0, \
/* vector */ ZYAN_VECTOR_INITIALIZER \
}
Defines an uninitialized ZyanString instance.
The initial minimum capacity (number of characters) for all dynamically allocated string instances - not including the terminating '\0'-character.
Casts a ZyanString pointer to a constant ZyanStringView pointer.
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.
Defines the ZyanStringFlags data-type.
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.
Appends the content of the source string to the end of the destination string.
Parameters
Returns
Appends count characters of the source string to the end of the destination string.
Parameters
Returns
Erases the given string.
Parameters
Returns
Compares two strings.
Parameters
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
Performs a case-insensitive comparison of two strings.
Parameters
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
Initializes a new ZyanString instance by concatenating two existing strings.
Parameters
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
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.
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
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
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.
Initializes a new ZyanString instance by concatenating two existing strings and sets a custom allocator and memory allocation/deallocation parameters.
Parameters
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
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.
Deletes characters from the given string, starting at index.
Parameters
Returns
Destroys the given ZyanString instance.
Parameters
Returns
Initializes a new ZyanString instance by duplicating an existing string.
Parameters
This value is automatically adjusted to the size of the source string, if
a smaller value was passed.
Returns
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.
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
This function will fail, if the capacity of the buffer is less or equal to the size of the source string.
Returns
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.
Initializes a new ZyanString instance by duplicating an existing string and sets a custom allocator and memory allocation/deallocation parameters.
Parameters
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
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.
Returns the current capacity of the string.
Parameters
Returns
Returns the character at the given index.
Parameters
Returns
Returns a pointer to the character at the given index.
Parameters
Returns
Returns the C-style string of the given ZyanString instance.
Parameters
Returns
Returns the current size (number of characters) of the string (excluding the terminating zero character).
Parameters
Returns
Initializes the given ZyanString instance.
Parameters
Returns
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.
Initializes the given ZyanString instance and configures it to use a custom user defined buffer with a fixed size.
Parameters
Returns
Finalization is not required for strings created by this function.
Initializes the given ZyanString instance and sets a custom allocator and memory allocation/deallocation parameters.
Parameters
Returns
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.
Inserts the content of the source string in the destination string at the given index.
Parameters
Returns
Inserts count characters of the source string in the destination string at the given index.
Parameters
Returns
Searches for the first occurrence of needle in the given haystack starting from the left.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Searches for the first occurrence of needle in the given haystack starting from the left.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Performs a case-insensitive search for the first occurrence of needle in the given haystack starting from the left.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Performs a case-insensitive search for the first occurrence of needle in the given haystack starting from the left.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Changes the capacity of the given ZyanString instance.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Resizes the given ZyanString instance.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Searches for the first occurrence of needle in the given haystack starting from the right.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Searches for the first occurrence of needle in the given haystack starting from the right.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Performs a case-insensitive search for the first occurrence of needle in the given haystack starting from the right.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Performs a case-insensitive search for the first occurrence of needle in the given haystack starting from the right.
Parameters
Returns
The found_index is set to -1, if the needle was not found.
Assigns a new value to the character at the given index.
Parameters
Returns
Shrinks the capacity of the given string to match it's size.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Converts the given string to lowercase letters.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Converts count characters of the given string to lowercase letters.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Converts the given string to uppercase letters.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Converts count characters of the given string to uppercase letters.
Parameters
Returns
This function will fail, if the ZYAN_STRING_IS_IMMUTABLE flag is set for the specified ZyanString instance.
Deletes all remaining characters from the given string, starting at index.
Parameters
Returns
Returns the C-style string of the given ZyanString instance.
Warning
Parameters
Returns
Returns the size (number of characters) of the view.
Parameters
Returns
Returns a view inside a null-terminated C-style string.
Parameters
Returns
Returns a view inside a character buffer with custom length.
Parameters
Returns
Returns a view inside an existing view/string.
Parameters
Returns
The ZYAN_STRING_TO_VEW macro can be used to pass any ZyanString instance as value for the source string.
Returns a view inside an existing view/string starting from the given index.
Parameters
Returns
The ZYAN_STRING_TO_VEW macro can be used to pass any ZyanString instance as value for the source string.
Generated automatically by Doxygen for Zycore from the source code.
| Version 1.5.2.0 | Zycore |