include/Zycore/String.h(3)

📦

version 1.5.2 · 2 versions

1.5.2 · ubuntu resolute, ubuntu stonking (latest)
1.5.2 · debian trixie, ubuntu questing

💖 NAME 💖

include/Zycore/String.h — bestie, it's the Zycore string situation, and it's giving everything. 🎀

So this is include/Zycore/String.h(3), from the Library Functions Manual. It's a header for a whole string type in Zycore, and we're breaking it down section by section. More parts are coming, so don't go anywhere. 💅

✨ SYNOPSIS ✨

Okay first, the includes. You need all of these, no cap:

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

🧸 Classes

struct ZyanString_
struct ZyanStringView_

🍓 Macros

These are the defines, exactly as they live:

#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

Miss girl, this list is long, and every single one is here. Read it and weep (affectionately):

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 🌈

It implements a string type. That's the whole vibe. A string type, but make it Zycore. 💜

🎀 MACRO DEFINITION DOCUMENTATION 🎀

`#define ZYAN_DEFINE_STRING_VIEW( string)`

Value — and bestie, this is exactly how it looks:

{ \
    /* 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. So it's like a little window you can peek through. 🪟

Parameters

string — the C-style string. That's the one.

`#define ZYAN_STRING_DEFAULT_GROWTH_FACTOR 2`

The default growth factor for all string instances. When it grows, it grows by this much. Periodt. ✨

`#define ZYAN_STRING_DEFAULT_SHRINK_THRESHOLD 4`

The default shrink threshold for all string instances. It's the "okay bestie, time to tighten up" number. 💅

`#define ZYAN_STRING_HAS_FIXED_CAPACITY 0x01`

The string uses a custom user-defined buffer with a fixed capacity. So it's not flexible — it is what it is, and what it is is fixed. 🫶

`#define ZYAN_STRING_INITIALIZER`

Value:

{ \
    /* flags  */ 0, \
    /* vector */ ZYAN_VECTOR_INITIALIZER \
}

Defines an uninitialized ZyanString instance. It's giving blank-slate energy. 🦋

`#define ZYAN_STRING_MIN_CAPACITY 32`

The initial minimum capacity (number of characters) for all dynamically allocated string instances — and this is important — not including the terminating '\0'-character. So 32 chars plus the null terminator. Don't forget the null terminator, bestie, it will humble you. 😭

`#define ZYAN_STRING_TO_VIEW( string)`

Value:

(const ZyanStringView*)(string)

Casts a ZyanString pointer to a constant ZyanStringView pointer. Glow-up via cast, zero runtime overhead. 👑

🧚 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. So like... don't touch. Respect the privacy, bestie. 🙈

`typedef ZyanU8 ZyanStringFlags`

Defines the ZyanStringFlags data-type. It's literally just a ZyanU8, but make it named. 💖

`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. So like... don't go holding onto a view after you've messed with the thing it's viewing. That's giving dangling pointer, and not in a cute way. 💀

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). Deep-copy = the safe way. Don't skip steps. 🎀

All fields in this struct should be considered as "private". Any changes may lead to unexpected behavior. Again — private. Hands off. 👀

🔥 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. Like adding a little ✨more✨ to the end of your sentence.

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. You pick where to start and how much to take. Choose wisely. 🍓

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. Gone. Deleted. Not a trace. 🫥

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

okay so here's what you're handing over 💖

s1 — the first string 🌸
s2 — the second string 🫶
result — receives the comparison result.

and the values result can end up with, no cap:

result < 0 → the first character that doesn't 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 doesn't match has a greater value in s1 than in s2

Returns

ZYAN_STATUS_TRUE if the strings are equal, ZYAN_STATUS_FALSE if they're 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. she does not care about your capital letters, bestie 👑

Parameters

s1 — the first string
s2 — the second string.
result — receives the comparison result.

Values it can receive:

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. it's giving ✨glow up✨, two strings becoming one.

heads up: this one is ZYAN_REQUIRES_LIBC, so she needs libc to do her thing 🫶

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. no self-concat shenanigans
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. she fixes your math for you 💅

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. like, undefined undefined. don't do it fr fr.

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. don't forget, i'm watching 👀

`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. you bring the storage, she brings the vibes 🎀

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. so give her room okay

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. so you can just... let her be 🦋

`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. main character energy, she gets to pick her own everything 👑

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. pick your poison 💀

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. and just like that, gone ✨

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. it's over bestie 😭💔 (but like, in a memory-management way)

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. twin where 🫶

this one is ZYAN_REQUIRES_LIBC too, so libc is required

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. yes she'll use your buffer, she's not picky like that 🎀

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. so yes the '\0' counts, that's the whole point 👑

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. custom everything, she said "i have a vision" 💅

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. she's telling you how much room she has 🌸

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. just one lil guy 🦋

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. a pointer, note the char ** — she wants you to be able to touch it 😌

string — a pointer to the ZyanString instance 💖
index — the character index 🌸
value — this one receives a pointer to the character you wanted, sitting right there in the string ✨

Returns: a zyan status code 🫶

`ZYCORE_EXPORT ZyanStatus ZyanStringGetData (const ZyanString * string, const char ** value)`

Hands you the C-style string of the given ZyanString instance — like, the actual char-pointer era version. no cap 🎀

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

Tells you the current size — that's the number of characters, and bestie, it does not count the terminating zero character. the '\0' is not invited to this count 💅

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

Sets up the given ZyanString instance. brand new, sparkling, ready for content ✨

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 gets dynamically allocated by the default allocator, using the default growth factor and the default shrink threshold. defaults everywhere, it's giving low-effort slay 💅

The allocated buffer will be at least one character larger than the given capacity, so there's always room reserved for that terminating '\0'. she saves a seat 🪑

Finalization with ZyanStringDestroy is required for all strings created by this function. don't ghost her, ok? 😭

`ZYCORE_EXPORT ZyanStatus ZyanStringInitCustomBuffer (ZyanString * string, char * buffer, ZyanUSize capacity)`

Sets up the given ZyanString instance and tells it to use a custom user defined buffer with a fixed size. your buffer, your rules 👑

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' ⚠️ yes bestie, this one counts the zero 🫠

Returns: a zyan status code ⭐

Finalization is not required for strings created by this function. she's self-sufficient, main character energy 💅

`ZYCORE_EXPORT ZyanStatus ZyanStringInitEx (ZyanString * string, ZyanUSize capacity, ZyanAllocator * allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold)`

Sets up the given ZyanString instance and lets you set a custom allocator plus your own memory allocation/deallocation parameters. full DIY mode 🔧

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. noted 📝

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. again — do not forget her 😭

`ZYCORE_EXPORT ZyanStatus ZyanStringInsert (ZyanString * destination, ZyanUSize index, const ZyanStringView * source)`

Inserts the content of the source string into the destination string at the given index. sneaking text in at exactly the right spot, we love to see it ✨

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 into the destination string at the given index. it's the same vibe as ZyanStringInsert but now you get to pick which characters and how many 💅

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. classic needle-in-haystack detective work 🔎

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. not found = -1, always 😤

`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. same hunt, but now you control the range 🗺️

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

Does a case-insensitive search for the first occurrence of needle in the given haystack, starting from the left. "BESTIE" and "bestie" are the same girl, periodt 💅

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

Does a case-insensitive search for the first occurrence of needle in the given haystack, starting from the left. case-insensitive and range-limited, she does it all 💖

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. glow-up for the buffer allocation 🎀

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. she said no changes, and she meant it 💀

`ZYCORE_EXPORT ZyanStatus ZyanStringResize (ZyanString * string, ZyanUSize size)`

Resizes the given ZyanString instance. growing or shrinking, whatever the era calls for ✨

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. immutability check said nope 🙈

`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. she's walking backwards through the text, iconic 🔙

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. right-to-left but make it bounded 🗺️

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

Does a case-insensitive search for the first occurrence of needle in the given haystack, starting from the right. right side, no case sensitivity, all vibes 🦋

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

Does a case-insensitive search for the first occurrence of needle in the given haystack, starting from the right. the final boss of search functions, and she ate 🔥

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)

okay so this one is literally assigning a new value to the character at the given index. it's giving single-character glow-up 💅

Parameters

string — a pointer to the ZyanString instance.
index — the character index.
value — the character to assign.

Returns

A zyan status code. slay.

`ZyanStringShrinkToFit` 🎀

ZYCORE_EXPORT ZyanStatus ZyanStringShrinkToFit (ZyanString * string)

Shrinks the capacity of the given string to match it's size. yes bestie, it's giving "snatched to the exact fit" 💅

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. lowercase era activated. ✨

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. uppercase main character energy. 💅

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. it's giving "cut the chat, we're done here" 💀

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.

Author 💖

Generated automatically by Doxygen for Zycore from the source code.

That's the whole page, bestie! Zycore, Version 1.5.2.0, from include/Zycore/String.h(3) — periodt. 💅✨

📦 where this page comes from

ubuntu resolute: libzycore-doc 1.5.2-1build1 · MIT
ubuntu stonking: libzycore-doc 1.5.2-1build1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms