String utilities. More...

#include <system/kzs_types.h>
#include <system/debug/kzs_error.h>
#include <system/wrappers/kzs_arg.h>
#include <system/kzs_header.h>

Data Structures
struct	KzcStringIterator
	String iterator for unicode characters. More...

Macros
#define	KZC_STRING_TERMINATION_SYMBOL
	Constant for string termination character. More...

#define	KZC_STRING_UNICODE_REPLACEMENT_CHARACTER
	Constant for unicode replacement character. More...

#define	kzcStringIterate(iterator_param)
	Finds the next entry in the attached hash map. More...

#define	kzcStringIteratorGetValue(iterator_param)
	Returns the value of the hash map entry pointed by the iterator. More...

Functions
kzsError	kzcStringCreate (const struct KzcMemoryManager memoryManager, kzUint size, kzMutableString out_string)
	Creates a new mutable string of given size and terminates it with '\0' from the start. More...

kzsError	kzcStringAllocate (const struct KzcMemoryManager memoryManager, kzUint length, kzMutableString out_string)
	Creates a new string of given length. More...

kzsError	kzcStringCreateEmpty (const struct KzcMemoryManager memoryManager, kzMutableString out_string)
	Creates a new empty string. More...

kzsError	kzcStringDelete (kzMutableString string)
	Deletes a string. More...

kzUint	kzcStringLength (kzString string)
	Returns the length of a string. More...

kzBool	kzcStringIsEmpty (kzString string)
	Returns KZ_TRUE if the string is empty. More...

kzsError	kzcStringCopy (const struct KzcMemoryManager memoryManager, kzString source, kzMutableString out_target)
	Creates a copy of the given source string. More...

kzsError	kzcStringConcatenate (const struct KzcMemoryManager memoryManager, kzString front, kzString back, kzMutableString out_string)
	Concatenates two strings. More...

kzsError	kzcStringConcatenateMultiple (const struct KzcMemoryManager memoryManager, kzUint numStrings, kzMutableString out_string,...)
	Concatenates arbitrary number of strings. More...

kzsError	kzcStringSubstring (const struct KzcMemoryManager memoryManager, kzString string, kzUint start, kzUint length, kzMutableString out_string)
	Returns a substring of the given string starting from the given index and length characters long. More...

kzBool	kzcStringFindSubstring (kzString string, kzString subString, kzUint *out_index)
	Finds the first position where given sub string is located in the given string. More...

kzBool	kzcStringFindNextSubstring (kzString string, kzString subString, kzUint startIndex, kzUint *out_index)
	Finds the next position where given sub string is located in the given string. More...

kzUint	kzcStringGetSubstringCount (kzString string, kzString pattern)
	Returns the number of how many times given pattern exists as a substring in given string without overlapping. More...

kzBool	kzcStringFindCharacter (kzString string, kzChar ch, kzUint *out_index)
	Finds the first position where given character is located in the given string. More...

kzBool	kzcStringFindNextCharacter (kzString string, kzChar ch, kzUint startIndex, kzUint *out_index)
	Finds the next position where given character is located in the given string. More...

kzBool	kzcStringStartsWith (kzString string, kzString pattern)
	Checks if the given string starts with the given pattern. More...

kzBool	kzcStringEndsWith (kzString string, kzString pattern)
	Checks if the given string ends with the given pattern. More...

kzsError	kzcStringReplace (const struct KzcMemoryManager memoryManager, kzString originalString, kzString pattern, kzString patternReplacement, kzMutableString out_string)
	Replace instances of pattern in base. More...

void	kzcStringRemoveSubstringInPlace (kzMutableString string, kzString substring)
	Remove a substring from a string in-place. More...

kzBool	kzcStringToBool (kzString string)
	Parse input string to a boolean value. More...

kzInt	kzcStringToInt (kzString string)
	Parse input string to an integer value. More...

kzFloat	kzcStringToFloat (kzString string)
	Parse input string to a floating point value. More...

kzsError	kzcIntToString (const struct KzcMemoryManager memoryManager, kzInt value, kzMutableString out_string)
	Returns a string representation of integer. More...

kzsError	kzcFloatToString (const struct KzcMemoryManager memoryManager, kzFloat value, kzMutableString out_string)
	Returns an approximate string representation of a floating point value. More...

kzsError	kzcStringSplit (const struct KzcMemoryManager memoryManager, kzString string, kzString separator, kzUint out_stringCount, kzMutableString **out_strings)
	Splits the string by the given separator into an array of strings. More...

kzsError	kzcStringJoin (const struct KzcMemoryManager memoryManager, kzUint stringCount, const kzString strings, kzString delimiter, kzMutableString *out_string)
	Joins the given string array with a given delimiter to a single string. More...

kzsError	kzcStringAsciiToLowerCase (const struct KzcMemoryManager memoryManager, kzString sourceString, kzMutableString out_string)
	Creates string that contains lower case letters from source string. More...

kzsError	kzcStringFormatGetLength (kzString format, KZ_CONST_ARGLIST kzArgList arguments, kzUint out_length)
	Get the formatted length of the string. More...

kzsError	kzcStringFormatList (const struct KzcMemoryManager memoryManager, kzString format, KZ_CONST_ARGLIST kzArgList arguments, kzMutableString *out_string)
	vsnprintf()-like string formatter. More...

kzsError	kzcStringFormat (const struct KzcMemoryManager memoryManager, kzString format, kzMutableString out_string,...)
	Formats the given string with given parameters. More...

kzInt	kzcStringCompare (kzString first, kzString second)
	Compare two strings. More...

kzInt	kzcStringCompareWithLength (kzString first, kzString second, kzUint length)
	Compare two strings but only look at most length characters. More...

kzInt	kzcStringCompareIgnoreAsciiCase (kzString first, kzString second)
	Compare two strings ignoring case for characters in the range A-Z and a-z. More...

kzInt	kzcStringCompareIgnoreAsciiCaseWithLength (kzString first, kzString second, kzUint length)
	Compare two strings ignoring case for characters in the range A-Z and a-z, but only look at most length characters. More...

kzBool	kzcStringIsEqual (kzString first, kzString second)
	Compare two strings. More...

kzBool	kzcStringIsEqualNullSafe (kzString first, kzString second)
	Compare two strings. More...

kzUint	kzcStringGetUnicodeLength (kzString string)
	Returns the number of unicode characters in given UTF-8 encoded string. More...

kzUnicodeChar	kzcStringGetUnicodeCharacter (kzString string, kzUint *out_byteReadCount)
	Returns the unicode code point at the beginning of given string in UTF-8 format. More...

kzUint	kzcStringWriteUnicodeCharacter (kzMutableString string, kzUnicodeChar character)
	Encodes the given unicode character in UTF-8 format to the given string. More...

kzsError	kzcStringToUnicodeArray (const struct KzcMemoryManager memoryManager, kzString string, kzUint out_characterCount, kzUnicodeChar **out_unicodeCharacters)
	Decodes the given UTF-8 encoded string to an array of unicode code points. More...

kzsError	kzcStringFromUnicodeArray (const struct KzcMemoryManager memoryManager, kzUint arrayLength, const kzUnicodeChar unicodeArray, kzMutableString *out_string)
	Encodes the given array of unicode code points to UTF-8 string. More...

struct KzcStringIterator	kzcStringGetIterator (kzString string)
	Get unicode iterator for given UTF-8 string. More...

kzBool	kzcStringIterate_private (struct KzcStringIterator *iterator)

kzUnicodeChar	kzcStringIteratorGetValue_private (const struct KzcStringIterator *iterator)

kzBool	kzcStringAsciiCharIsSpace (kzChar character)
	Test whether or not a certain character is whitespace. More...

kzMutableString	kzcStringTrim (kzMutableString input)
	In-place string trim. More...

Detailed Description

String utilities.

Macro Definition Documentation

#define KZC_STRING_TERMINATION_SYMBOL

Constant for string termination character.

#define KZC_STRING_UNICODE_REPLACEMENT_CHARACTER

Constant for unicode replacement character.

#define kzcStringIterate ( iterator_param)

Finds the next entry in the attached hash map.

Returns KZ_TRUE if next entry is found, otherwise KZ_FALSE.

#define kzcStringIteratorGetValue ( iterator_param)

Returns the value of the hash map entry pointed by the iterator.

Function Documentation

kzsError kzcStringCreate	(	const struct KzcMemoryManager *	memoryManager,
		kzUint	size,
		kzMutableString *	out_string
	)

Creates a new mutable string of given size and terminates it with '\0' from the start.

The string can contain size - 1 characters in addition to the terminating character.

kzsError kzcStringAllocate	(	const struct KzcMemoryManager *	memoryManager,
		kzUint	length,
		kzMutableString *	out_string
	)

Creates a new string of given length.

Terminating '\0' is not counted in the length. The resulting string is not initialized and does not have terminating '\0'.

kzsError kzcStringCreateEmpty	(	const struct KzcMemoryManager *	memoryManager,
		kzMutableString *	out_string
	)

Creates a new empty string.

The resulting zero-length string is '\0' terminated.

kzsError kzcStringDelete ( kzMutableString string)

Deletes a string.

kzUint kzcStringLength ( kzString string)

Returns the length of a string.

Terminating '\0' is not counted. Note that this function returns the number of UTF-8 bytes, not the number of unicode code points in it.

kzBool kzcStringIsEmpty ( kzString string)

Returns KZ_TRUE if the string is empty.

kzsError kzcStringCopy	(	const struct KzcMemoryManager *	memoryManager,
		kzString	source,
		kzMutableString *	out_target
	)

Creates a copy of the given source string.

kzsError kzcStringConcatenate	(	const struct KzcMemoryManager *	memoryManager,
		kzString	front,
		kzString	back,
		kzMutableString *	out_string
	)

Concatenates two strings.

kzsError kzcStringConcatenateMultiple	(	const struct KzcMemoryManager *	memoryManager,
		kzUint	numStrings,
		kzMutableString *	out_string,
			...
	)

Concatenates arbitrary number of strings.

kzsError kzcStringSubstring	(	const struct KzcMemoryManager *	memoryManager,
		kzString	string,
		kzUint	start,
		kzUint	length,
		kzMutableString *	out_string
	)

Returns a substring of the given string starting from the given index and length characters long.

If length would go out of bounds of the string it is silently clamped to the end of the string.

kzBool kzcStringFindSubstring	(	kzString	string,
		kzString	subString,
		kzUint *	out_index
	)

Finds the first position where given sub string is located in the given string.

Returns the index of the first letter which is part of the search string Returns false if the pattern is not found.

Parameters

out_index Index from the beginning of the string, KZ_NULL if not used.

kzBool kzcStringFindNextSubstring	(	kzString	string,
		kzString	subString,
		kzUint	startIndex,
		kzUint *	out_index
	)

Finds the next position where given sub string is located in the given string.

Search is started from the given index, which must be smaller than the length of the string. Returns false if the pattern is not found.

Parameters

out_index Index from the beginning of the string, KZ_NULL if not used.

kzUint kzcStringGetSubstringCount	(	kzString	string,
		kzString	pattern
	)

Returns the number of how many times given pattern exists as a substring in given string without overlapping.

kzBool kzcStringFindCharacter	(	kzString	string,
		kzChar	ch,
		kzUint *	out_index
	)

Finds the first position where given character is located in the given string.

Returns false if the character is not found.

kzBool kzcStringFindNextCharacter	(	kzString	string,
		kzChar	ch,
		kzUint	startIndex,
		kzUint *	out_index
	)

Finds the next position where given character is located in the given string.

Search is started from the given index, which must be smaller than the length of the string. Returns false if the character is not found.

kzBool kzcStringStartsWith	(	kzString	string,
		kzString	pattern
	)

Checks if the given string starts with the given pattern.

kzBool kzcStringEndsWith	(	kzString	string,
		kzString	pattern
	)

Checks if the given string ends with the given pattern.

kzsError kzcStringReplace	(	const struct KzcMemoryManager *	memoryManager,
		kzString	originalString,
		kzString	pattern,
		kzString	patternReplacement,
		kzMutableString *	out_string
	)

Replace instances of pattern in base.

Return resulting string in out_string. 'out_string' is assigned new memory from heap.

void kzcStringRemoveSubstringInPlace	(	kzMutableString	string,
		kzString	substring
	)

Remove a substring from a string in-place.

kzBool kzcStringToBool ( kzString string)

Parse input string to a boolean value.

String literals "true" and "false" are accepted. Integer values that are not 1 or 0 will be interpreted as KZ_TRUE.

Parameters

string String to parse.

Returns: Boolean value parsed from string or KZ_FALSE if the string contains an invalid boolean value.

kzInt kzcStringToInt ( kzString string)

Parse input string to an integer value.

Parameters

string String to parse.

Returns: Integer value parsed from string or 0 if the string contains an invalid number.

kzFloat kzcStringToFloat ( kzString string)

Parse input string to a floating point value.

Parameters

string String to parse.

Returns: Floating-point value parsed from string or 0.0f if the string contains an invalid number.

kzsError kzcIntToString	(	const struct KzcMemoryManager *	memoryManager,
		kzInt	value,
		kzMutableString *	out_string
	)

Returns a string representation of integer.

kzsError kzcFloatToString	(	const struct KzcMemoryManager *	memoryManager,
		kzFloat	value,
		kzMutableString *	out_string
	)

Returns an approximate string representation of a floating point value.

kzsError kzcStringSplit	(	const struct KzcMemoryManager *	memoryManager,
		kzString	string,
		kzString	separator,
		kzUint *	out_stringCount,
		kzMutableString **	out_strings
	)

Splits the string by the given separator into an array of strings.

The separator symbol is not included in the output string.

kzsError kzcStringJoin	(	const struct KzcMemoryManager *	memoryManager,
		kzUint	stringCount,
		const kzString *	strings,
		kzString	delimiter,
		kzMutableString *	out_string
	)

Joins the given string array with a given delimiter to a single string.

kzsError kzcStringAsciiToLowerCase	(	const struct KzcMemoryManager *	memoryManager,
		kzString	sourceString,
		kzMutableString *	out_string
	)

Creates string that contains lower case letters from source string.

This function only modifies characters in the range A-Z.

kzsError kzcStringFormatGetLength	(	kzString	format,
		KZ_CONST_ARGLIST kzArgList *	arguments,
		kzUint *	out_length
	)

Get the formatted length of the string.

kzsError kzcStringFormatList	(	const struct KzcMemoryManager *	memoryManager,
		kzString	format,
		KZ_CONST_ARGLIST kzArgList *	arguments,
		kzMutableString *	out_string
	)

vsnprintf()-like string formatter.

Format parameter specifies how the resulting string is formatted. Arguments parameter provides the formatting arguments as variable arguments list.

Parameters

out_string Newly allocated, formatted string. Free with kzcStringDelete().

See Also: kzcStringFormat for format information.

kzsError kzcStringFormat	(	const struct KzcMemoryManager *	memoryManager,
		kzString	format,
		kzMutableString *	out_string,
			...
	)

Formats the given string with given parameters.

Format parameter specifies how the resulting string is formatted. Formatting arguments are given as variable arguments.

Format flags:

%[flags][width][.precision]type Alternatively %% produces a single % character.

flags: - Use left alignment for output

Use sign for non-negative numbers also 0 Use leading zeros for padding, when width is specified

Flags must appear in the order listed above.

width: Any positive number. Output will be padded with spaces until it is at least this number of characters wide. Output will then be right-aligned by default.

precision: Precision is available only for floating point types. Exactly this number of decimal digits will be outputted.

Type char Actual type Format i/d kzInt Signed integer u kzUint Unsigned integer f kzFloat printed in scientific notation if not enough space for decimal notation x kzUint Lowercase hexadecimal integer (badf00d) X kzUint Uppercase hexadecimal integer (BADF00D) s kzString String c kzChar ASCII character C kzUnicodeChar Unicode character b kzBool Lowercase boolean string (true or false) B kzBool Boolean string with first letter uppercase (True or False) p void* Memory pointer

An error is thrown, if the format is not meaningful (eg. %+b, %5.5i or %-i).

kzInt kzcStringCompare	(	kzString	first,
		kzString	second
	)

Compare two strings.

Return -1 if first < second, 0 if first == second and 1 if first > second.

kzInt kzcStringCompareWithLength	(	kzString	first,
		kzString	second,
		kzUint	length
	)

Compare two strings but only look at most length characters.

Return -1 if first < second, 0 if first == second and 1 if first > second.

kzInt kzcStringCompareIgnoreAsciiCase	(	kzString	first,
		kzString	second
	)

Compare two strings ignoring case for characters in the range A-Z and a-z.

Returns negative number if first < second, 0 if first == second, poisitive number if first > second.

kzInt kzcStringCompareIgnoreAsciiCaseWithLength	(	kzString	first,
		kzString	second,
		kzUint	length
	)

Compare two strings ignoring case for characters in the range A-Z and a-z, but only look at most length characters.

Returns negative number if first < second, 0 if first == second, poisitive number if first > second.

kzBool kzcStringIsEqual	(	kzString	first,
		kzString	second
	)

Compare two strings.

Return KZ_TRUE if the strings are equal.

kzBool kzcStringIsEqualNullSafe	(	kzString	first,
		kzString	second
	)

Compare two strings.

Return KZ_TRUE if the strings are equal. It is safe to pass KZ_NULL arguments to this function. KZ_NULL is equal only to KZ_NULL.

kzUint kzcStringGetUnicodeLength ( kzString string)

Returns the number of unicode characters in given UTF-8 encoded string.

kzUnicodeChar kzcStringGetUnicodeCharacter	(	kzString	string,
		kzUint *	out_byteReadCount
	)

Returns the unicode code point at the beginning of given string in UTF-8 format.

Number of bytes read for the unicode code point is stored in out_byteReadCount.

kzUint kzcStringWriteUnicodeCharacter	(	kzMutableString	string,
		kzUnicodeChar	character
	)

Encodes the given unicode character in UTF-8 format to the given string.

Number of bytes written is returned. 0 is returned, if the given character is invalid unicode code point. The string must be preallocated and have enough space for the necessary UTF-8 bytes of the unicode character.

kzsError kzcStringToUnicodeArray	(	const struct KzcMemoryManager *	memoryManager,
		kzString	string,
		kzUint *	out_characterCount,
		kzUnicodeChar **	out_unicodeCharacters
	)

Decodes the given UTF-8 encoded string to an array of unicode code points.

New memory is allocated for out_unicodeArray, which must be manually freed.

kzsError kzcStringFromUnicodeArray	(	const struct KzcMemoryManager *	memoryManager,
		kzUint	arrayLength,
		const kzUnicodeChar *	unicodeArray,
		kzMutableString *	out_string
	)

Encodes the given array of unicode code points to UTF-8 string.

New string is allocated for out_string, which must be manually deleted with kzcStringDelete().

struct KzcStringIterator kzcStringGetIterator ( kzString string)

Get unicode iterator for given UTF-8 string.

kzBool kzcStringIterate_private ( struct KzcStringIterator * iterator)

See Also: kzcStringIterate

kzUnicodeChar kzcStringIteratorGetValue_private ( const struct KzcStringIterator * iterator)

See Also: kzcStringIteratorGetValue

kzBool kzcStringAsciiCharIsSpace ( kzChar character)

Test whether or not a certain character is whitespace.

kzMutableString kzcStringTrim ( kzMutableString input)

In-place string trim.

Modifies the source string.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation