mirrors/dynarmic
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
dynarmic/include/Zycore/String.h
Alexandre Bouvier cd2ede593a Squashed 'externals/zycore/' changes from 0c372cde..1401fb85 
1401fb85 Fix `a label can only be part of a statement` warning (#61)
5f650a18 CMake: Enable `CMAKE_MSVC_RUNTIME_LIBRARY` (MSVC)
6c958cfe Fix no-libc build on "other" platforms (#58)
59819206 Bump version to v1.4.0
4bc563f6 Fix build-system to better work with vcpkg (#56)
4a8b5e2a CMake: rename target `doc` -> `ZycoreDoc`
a754e112 Bump version to 1.3.0
3e95307d Add support for ppc(64) and riscv64 (#52)
8f39333a build: only enable CXX if needed
7bd75696 build: add doc target
7c33e13e Fix `ZYAN_TRUE`/`ZYAN_FALSE` signedness
a0feec7f Fix warning `C4668`
bdbd3ff4 Bump version to v1.2
60b6ef1c Fix for dynamic libraries too
310f362c Adding ARCHIVE DESTINATION to fix CMake error
b01063b8 Improved logic for enabling LTO
c58d7fb5 Don't enable C11 for MSVC
ee784564 Switch minimum C standard supported to C11
5c341bf1 Implement an initial set of cross-compiler atomic operations
b4949ccc Minor fixes
9a305f6a Add CI workflow
dd2211a0 Get rid of CMake export headers
f0fb3f78 Fix `ZYAN_VECTOR_FOREACH_MUTABLE` macro
3f263290 format: handle encoding on wasm
95d7fb6c format: handle hex encoding on wasm
0d37fc54 defines: add wasm/wasi detection
8983325b build: use -pthread when possible
3de49d41 build: use system GTest when available
8d46cb58 test: make tests runnable with ctest
636bb299 Remove `float`s from the project (kernel mode compatibility) (#36)
e2b37b10 Assert to ensure sane growth factors
94185407 Added limits for integer types
767719d9 build(cmake): export and install zyan_* functions (#33)
6c93d9a3 build(cmake): add version and soversion to the library
fc2798d4 build(cmake): fix PUBLIC include dir of installed lib
22ce9c2d Add `ZYAN_FORCE_ASSERTS` CMake option
9a301424 Remove disabling source files in no-libc mode in CMake
3be54fca Thread.c: add missing SDK prototypes for old versions of Windows
d7fc85fd Exclude API/Memory.c and API/Process.c from compilation in no-libc mode
8da0001a Add back #ifdef guards to "API" headers/sources for no-libc mode
f6a48866 Fix cmake config files (#27)
4f3746fa Merge pull request #26 from Tsn0w/master
a9bb54ad Replace fallthrough attribute to __fallthrough__
99a74acb Add `ZYDIS_NOINLINE` macro

git-subtree-dir: externals/zycore
git-subtree-split: 1401fb85ac313f6605ec795c52bf99ea3f292a69
2022-11-20 21:49:18 +01:00

1011 lines
41 KiB
C
Raw Blame History

/***************************************************************************************************
Zyan Core Library (Zycore-C)
Original Author : Florian Bernd
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
***************************************************************************************************/
/**
* @file
* Implements a string type.
*/
#ifndef ZYCORE_STRING_H
#define ZYCORE_STRING_H
#include <Zycore/Allocator.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>
#include <Zycore/Vector.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ============================================================================================== */
/* Constants */
/* ============================================================================================== */
/**
* The initial minimum capacity (number of characters) for all dynamically allocated
* string instances - not including the terminating '\0'-character.
*/
#define ZYAN_STRING_MIN_CAPACITY 32
/**
* The default growth factor for all string instances.
*/
#define ZYAN_STRING_DEFAULT_GROWTH_FACTOR 2
/**
* The default shrink threshold for all string instances.
*/
#define ZYAN_STRING_DEFAULT_SHRINK_THRESHOLD 4
/* ============================================================================================== */
/* Enums and types */
/* ============================================================================================== */
/* ---------------------------------------------------------------------------------------------- */
/* String flags */
/* ---------------------------------------------------------------------------------------------- */
/**
* Defines the `ZyanStringFlags` data-type.
*/
typedef ZyanU8 ZyanStringFlags;
/**
* The string uses a custom user-defined buffer with a fixed capacity.
*/
#define ZYAN_STRING_HAS_FIXED_CAPACITY 0x01 // (1 << 0)
/* ---------------------------------------------------------------------------------------------- */
/* String */
/* ---------------------------------------------------------------------------------------------- */
/**
* 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 struct ZyanString_
{
/**
* String flags.
*/
ZyanStringFlags flags;
/**
* The vector that contains the actual string.
*/
ZyanVector vector;
} ZyanString;
/* ---------------------------------------------------------------------------------------------- */
/* View */
/* ---------------------------------------------------------------------------------------------- */
/**
* 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.
*/
typedef struct ZyanStringView_
{
/**
* The string data.
*
* The view internally re-uses the normal string struct to allow casts without any runtime
* overhead.
*/
ZyanString string;
} ZyanStringView;
/* ---------------------------------------------------------------------------------------------- */
/* ============================================================================================== */
/* Macros */
/* ============================================================================================== */
/* ---------------------------------------------------------------------------------------------- */
/* General */
/* ---------------------------------------------------------------------------------------------- */
/**
* Defines an uninitialized `ZyanString` instance.
*/
#define ZYAN_STRING_INITIALIZER \
{ \
/* flags */ 0, \
/* vector */ ZYAN_VECTOR_INITIALIZER \
}
/* ---------------------------------------------------------------------------------------------- */
/* Helper macros */
/* ---------------------------------------------------------------------------------------------- */
/**
* Casts a `ZyanString` pointer to a constant `ZyanStringView` pointer.
*/
#define ZYAN_STRING_TO_VIEW(string) (const ZyanStringView*)(string)
/**
* Defines a `ZyanStringView` struct that provides a view into a static C-style string.
*
* @param string The C-style string.
*/
#define ZYAN_DEFINE_STRING_VIEW(string) \
{ \
/* 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) \
} \
} \
}
/* ---------------------------------------------------------------------------------------------- */
/* ============================================================================================== */
/* Exported functions */
/* ============================================================================================== */
/* ---------------------------------------------------------------------------------------------- */
/* Constructor and destructor */
/* ---------------------------------------------------------------------------------------------- */
#ifndef ZYAN_NO_LIBC
/**
* Initializes the given `ZyanString` instance.
*
* @param string A pointer to the `ZyanString` instance.
* @param capacity The initial capacity (number of characters).
*
* @return 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 ZYAN_REQUIRES_LIBC ZyanStatus ZyanStringInit(ZyanString* string, ZyanUSize capacity);
#endif // ZYAN_NO_LIBC
/**
* Initializes the given `ZyanString` instance and sets a custom `allocator` and memory
* allocation/deallocation parameters.
*
* @param string A pointer to the `ZyanString` instance.
* @param capacity The initial capacity (number of characters).
* @param allocator A pointer to a `ZyanAllocator` instance.
* @param growth_factor The growth factor.
* @param shrink_threshold The shrink threshold.
*
* @return 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 ZyanStringInitEx(ZyanString* string, ZyanUSize capacity,
ZyanAllocator* allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold);
/**
* Initializes the given `ZyanString` instance and configures it to use a custom user
* defined buffer with a fixed size.
*
* @param string A pointer to the `ZyanString` instance.
* @param buffer A pointer to the buffer that is used as storage for the string.
* @param capacity The maximum capacity (number of characters) of the buffer, including
* the terminating '\0'.
*
* @return A zyan status code.
*
* Finalization is not required for strings created by this function.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringInitCustomBuffer(ZyanString* string, char* buffer,
ZyanUSize capacity);
/**
* Destroys the given `ZyanString` instance.
*
* @param string A pointer to the `ZyanString` instance.
*
* @return A zyan status code.
*
*/
ZYCORE_EXPORT ZyanStatus ZyanStringDestroy(ZyanString* string);
/* ---------------------------------------------------------------------------------------------- */
/* Duplication */
/* ---------------------------------------------------------------------------------------------- */
#ifndef ZYAN_NO_LIBC
/**
* Initializes a new `ZyanString` instance by duplicating an existing string.
*
* @param destination A pointer to the (uninitialized) destination `ZyanString` instance.
* @param source A pointer to the source string.
* @param 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.
*
* @return 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 ZYAN_REQUIRES_LIBC ZyanStatus ZyanStringDuplicate(ZyanString* destination,
const ZyanStringView* source, ZyanUSize capacity);
#endif // ZYAN_NO_LIBC
/**
* Initializes a new `ZyanString` instance by duplicating an existing string and sets a
* custom `allocator` and memory allocation/deallocation parameters.
*
* @param destination A pointer to the (uninitialized) destination `ZyanString` instance.
* @param source A pointer to the source string.
* @param 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.
* @param allocator A pointer to a `ZyanAllocator` instance.
* @param growth_factor The growth factor.
* @param shrink_threshold The shrink threshold.
*
* @return 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 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
* configures it to use a custom user defined buffer with a fixed size.
*
* @param destination A pointer to the (uninitialized) destination `ZyanString` instance.
* @param source A pointer to the source string.
* @param buffer A pointer to the buffer that is used as storage for the string.
* @param 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.
*
* @return 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 ZyanStringDuplicateCustomBuffer(ZyanString* destination,
const ZyanStringView* source, char* buffer, ZyanUSize capacity);
/* ---------------------------------------------------------------------------------------------- */
/* Concatenation */
/* ---------------------------------------------------------------------------------------------- */
#ifndef ZYAN_NO_LIBC
/**
* Initializes a new `ZyanString` instance by concatenating two existing strings.
*
* @param destination A pointer to the (uninitialized) destination `ZyanString` instance.
*
* This function will fail, if the destination `ZyanString` instance equals
* one of the source strings.
* @param s1 A pointer to the first source string.
* @param s2 A pointer to the second source string.
* @param 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.
*
* @return 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 ZYAN_REQUIRES_LIBC ZyanStatus ZyanStringConcat(ZyanString* destination,
const ZyanStringView* s1, const ZyanStringView* s2, ZyanUSize capacity);
#endif // ZYAN_NO_LIBC
/**
* Initializes a new `ZyanString` instance by concatenating two existing strings and sets
* a custom `allocator` and memory allocation/deallocation parameters.
*
* @param destination A pointer to the (uninitialized) destination `ZyanString` instance.
*
* This function will fail, if the destination `ZyanString` instance
* equals one of the source strings.
* @param s1 A pointer to the first source string.
* @param s2 A pointer to the second source string.
* @param 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.
* @param allocator A pointer to a `ZyanAllocator` instance.
* @param growth_factor The growth factor.
* @param shrink_threshold The shrink threshold.
*
* @return 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 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
* configures it to use a custom user defined buffer with a fixed size.
*
* @param destination A pointer to the (uninitialized) destination `ZyanString` instance.
*
* This function will fail, if the destination `ZyanString` instance equals
* one of the source strings.
* @param s1 A pointer to the first source string.
* @param s2 A pointer to the second source string.
* @param buffer A pointer to the buffer that is used as storage for the string.
* @param 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.
*
* @return 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 ZyanStringConcatCustomBuffer(ZyanString* destination,
const ZyanStringView* s1, const ZyanStringView* s2, char* buffer, ZyanUSize capacity);
/* ---------------------------------------------------------------------------------------------- */
/* Views */
/* ---------------------------------------------------------------------------------------------- */
/**
* Returns a view inside an existing view/string.
*
* @param view A pointer to the `ZyanStringView` instance.
* @param source A pointer to the source string.
*
* @return 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 ZyanStringViewInsideView(ZyanStringView* view,
const ZyanStringView* source);
/**
* Returns a view inside an existing view/string starting from the given `index`.
*
* @param view A pointer to the `ZyanStringView` instance.
* @param source A pointer to the source string.
* @param index The start index.
* @param count The number of characters.
*
* @return 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 a null-terminated C-style string.
*
* @param view A pointer to the `ZyanStringView` instance.
* @param string The C-style string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringViewInsideBuffer(ZyanStringView* view, const char* string);
/**
* Returns a view inside a character buffer with custom length.
*
* @param view A pointer to the `ZyanStringView` instance.
* @param buffer A pointer to the buffer containing the string characters.
* @param length The length of the string (number of characters).
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringViewInsideBufferEx(ZyanStringView* view, const char* buffer,
ZyanUSize length);
/**
* Returns the size (number of characters) of the view.
*
* @param view A pointer to the `ZyanStringView` instance.
* @param size Receives the size (number of characters) of the view.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringViewGetSize(const ZyanStringView* view, ZyanUSize* size);
/**
* Returns the C-style string of the given `ZyanString` instance.
*
* @warning The string is not guaranteed to be null terminated!
*
* @param view A pointer to the `ZyanStringView` instance.
* @param buffer Receives a pointer to the C-style string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringViewGetData(const ZyanStringView* view, const char** buffer);
/* ---------------------------------------------------------------------------------------------- */
/* Character access */
/* ---------------------------------------------------------------------------------------------- */
/**
* Returns the character at the given `index`.
*
* @param string A pointer to the `ZyanStringView` instance.
* @param index The character index.
* @param value Receives the desired character of the string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringGetChar(const ZyanStringView* string, ZyanUSize index,
char* value);
/**
* Returns a pointer to the character at the given `index`.
*
* @param string A pointer to the `ZyanString` instance.
* @param index The character index.
* @param value Receives a pointer to the desired character in the string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringGetCharMutable(ZyanString* string, ZyanUSize index,
char** value);
/**
* Assigns a new value to the character at the given `index`.
*
* @param string A pointer to the `ZyanString` instance.
* @param index The character index.
* @param value The character to assign.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringSetChar(ZyanString* string, ZyanUSize index, char value);
/* ---------------------------------------------------------------------------------------------- */
/* Insertion */
/* ---------------------------------------------------------------------------------------------- */
/**
* Inserts the content of the source string in the destination string at the given `index`.
*
* @param destination The destination string.
* @param index The insert index.
* @param source The source string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringInsert(ZyanString* destination, ZyanUSize index,
const ZyanStringView* source);
/**
* Inserts `count` characters of the source string in the destination string at the given
* `index`.
*
* @param destination The destination string.
* @param destination_index The insert index.
* @param source The source string.
* @param source_index The index of the first character to be inserted from the source
* string.
* @param count The number of chars to insert from the source string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringInsertEx(ZyanString* destination, ZyanUSize destination_index,
const ZyanStringView* source, ZyanUSize source_index, ZyanUSize count);
/* ---------------------------------------------------------------------------------------------- */
/* Appending */
/* ---------------------------------------------------------------------------------------------- */
/**
* Appends the content of the source string to the end of the destination string.
*
* @param destination The destination string.
* @param source The source string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringAppend(ZyanString* destination, const ZyanStringView* source);
/**
* Appends `count` characters of the source string to the end of the destination string.
*
* @param destination The destination string.
* @param source The source string.
* @param source_index The index of the first character to be appended from the source string.
* @param count The number of chars to append from the source string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringAppendEx(ZyanString* destination, const ZyanStringView* source,
ZyanUSize source_index, ZyanUSize count);
/* ---------------------------------------------------------------------------------------------- */
/* Deletion */
/* ---------------------------------------------------------------------------------------------- */
/**
* Deletes characters from the given string, starting at `index`.
*
* @param string A pointer to the `ZyanString` instance.
* @param index The index of the first character to delete.
* @param count The number of characters to delete.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringDelete(ZyanString* string, ZyanUSize index, ZyanUSize count);
/**
* Deletes all remaining characters from the given string, starting at `index`.
*
* @param string A pointer to the `ZyanString` instance.
* @param index The index of the first character to delete.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringTruncate(ZyanString* string, ZyanUSize index);
/**
* Erases the given string.
*
* @param string A pointer to the `ZyanString` instance.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringClear(ZyanString* string);
/* ---------------------------------------------------------------------------------------------- */
/* Searching */
/* ---------------------------------------------------------------------------------------------- */
/**
* Searches for the first occurrence of `needle` in the given `haystack` starting from the
* left.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
*
* @return `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 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.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
* @param index The start index.
* @param count The maximum number of characters to iterate, beginning from the start
* `index`.
*
* @return `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);
/**
* Performs a case-insensitive search for the first occurrence of `needle` in the given
* `haystack` starting from the left.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
*
* @return `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.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
* @param index The start index.
* @param count The maximum number of characters to iterate, beginning from the start
* `index`.
*
* @return `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 ZyanStringLPosIEx(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.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
*
* @return `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 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.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
* @param index The start index.
* @param count The maximum number of characters to iterate, beginning from the start
* `index`.
*
* @return `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);
/**
* Performs a case-insensitive search for the first occurrence of `needle` in the given
* `haystack` starting from the right.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
*
* @return `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.
*
* @param haystack The string to search in.
* @param needle The sub-string to search for.
* @param found_index A pointer to a variable that receives the index of the first occurrence of
* `needle`.
* @param index The start index.
* @param count The maximum number of characters to iterate, beginning from the start
* `index`.
*
* @return `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);
/* ---------------------------------------------------------------------------------------------- */
/* Comparing */
/* ---------------------------------------------------------------------------------------------- */
/**
* Compares two strings.
*
* @param s1 The first string
* @param s2 The second string.
* @param 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`.
*
* @return `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 ZyanStringCompare(const ZyanStringView* s1, const ZyanStringView* s2,
ZyanI32* result);
/**
* Performs a case-insensitive comparison of two strings.
*
* @param s1 The first string
* @param s2 The second string.
* @param 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`.
*
* @return `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);
/* ---------------------------------------------------------------------------------------------- */
/* Case conversion */
/* ---------------------------------------------------------------------------------------------- */
/**
* Converts the given string to lowercase letters.
*
* @param string A pointer to the `ZyanString` instance.
*
* @return 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 `count` characters of the given string to lowercase letters.
*
* @param string A pointer to the `ZyanString` instance.
* @param index The start index.
* @param count The number of characters to convert, beginning from the start `index`.
*
* @return 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 the given string to uppercase letters.
*
* @param string A pointer to the `ZyanString` instance.
*
* @return 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 `count` characters of the given string to uppercase letters.
*
* @param string A pointer to the `ZyanString` instance.
* @param index The start index.
* @param count The number of characters to convert, beginning from the start `index`.
*
* @return 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);
/* ---------------------------------------------------------------------------------------------- */
/* Memory management */
/* ---------------------------------------------------------------------------------------------- */
/**
* Resizes the given `ZyanString` instance.
*
* @param string A pointer to the `ZyanString` instance.
* @param size The new size of the string.
*
* @return 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);
/**
* Changes the capacity of the given `ZyanString` instance.
*
* @param string A pointer to the `ZyanString` instance.
* @param capacity The new minimum capacity of the string.
*
* @return 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 ZyanStringReserve(ZyanString* string, ZyanUSize capacity);
/**
* Shrinks the capacity of the given string to match it's size.
*
* @param string A pointer to the `ZyanString` instance.
*
* @return 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 ZyanStringShrinkToFit(ZyanString* string);
/* ---------------------------------------------------------------------------------------------- */
/* Information */
/* ---------------------------------------------------------------------------------------------- */
/**
* Returns the current capacity of the string.
*
* @param string A pointer to the `ZyanString` instance.
* @param capacity Receives the size of the string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringGetCapacity(const ZyanString* string, ZyanUSize* capacity);
/**
* Returns the current size (number of characters) of the string (excluding the
* terminating zero character).
*
* @param string A pointer to the `ZyanString` instance.
* @param size Receives the size (number of characters) of the string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringGetSize(const ZyanString* string, ZyanUSize* size);
/**
* Returns the C-style string of the given `ZyanString` instance.
*
* @param string A pointer to the `ZyanString` instance.
* @param value Receives a pointer to the C-style string.
*
* @return A zyan status code.
*/
ZYCORE_EXPORT ZyanStatus ZyanStringGetData(const ZyanString* string, const char** value);
/* ---------------------------------------------------------------------------------------------- */
/* ============================================================================================== */
#ifdef __cplusplus
}
#endif
#endif // ZYCORE_STRING_H
Reference in a new issue View git blame Copy permalink