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>

Classes
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
KANZI_API kzsError	kzcStringCreate (kzUint length, kzMutableString *out_string)
	Creates a new mutable string of given length and terminates it with '\0' from the start. More...

KANZI_API kzsError	kzcStringAllocate (kzUint length, kzMutableString *out_string)
	Creates a new string of given length. More...

KANZI_API kzsError	kzcStringAllocate (KzcMemoryManager memoryManager, kzUint length, kzMutableString out_string)
	Creates a new string of given length using specified memory manager. More...

KANZI_API kzsError	kzcStringCreateEmpty (kzMutableString *out_string)
	Creates a new empty string. More...

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

KANZI_API kzsError	kzcStringDelete (KzcMemoryManager *memoryManager, kzMutableString string)
	Deletes a string using specified memory manager. More...

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

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

KANZI_API kzsError	kzcStringCopy (kzString source, kzMutableString *out_target)
	Creates a copy of the given source string. More...

KANZI_API kzsError	kzcStringCopy (KzcMemoryManager memoryManager, kzString source, kzMutableString out_target)
	Creates a copy of the given source string using specified memory manager. More...

KANZI_API kzsError	kzcStringConcatenate (kzString front, kzString back, kzMutableString *out_string)
	Concatenates two strings. More...

KANZI_API kzsError	kzcStringConcatenateMultiple (kzUint numStrings, kzMutableString *out_string,...)
	Concatenates arbitrary number of strings. More...

KANZI_API kzsError	kzcStringSubstring (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...

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

KANZI_API 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...

KANZI_API 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...

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

KANZI_API 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...

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

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

KANZI_API kzsError	kzcStringReplace (kzString originalString, kzString pattern, kzString patternReplacement, kzMutableString *out_string)
	Replace instances of pattern in base. More...

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

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

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

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

KANZI_API kzsError	kzcIntToString (kzInt value, kzMutableString *out_string)
	Returns a string representation of integer. More...

KANZI_API kzsError	kzcFloatToString (kzFloat value, kzMutableString *out_string)
	Returns an approximate string representation of a floating point value. More...

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

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

KANZI_API kzsError	kzcStringAsciiToLowerCase (kzString sourceString, kzMutableString *out_string)
	Creates string that contains lower case letters from source string. More...

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

KANZI_API kzsError	kzcStringFormatList (kzString format, KZ_CONST_ARGLIST kzArgList arguments, kzMutableString out_string)
	vsnprintf()-like string formatter. More...

KANZI_API kzsError	kzcStringFormat (kzString format, kzMutableString *out_string,...)
	Formats the given string with given parameters. More...

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

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

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

KANZI_API 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...

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

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

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

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

KANZI_API 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...

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

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

KANZI_API kzBool	kzcStringIterate_private (struct KzcStringIterator *iterator)

KANZI_API kzUnicodeChar	kzcStringIteratorGetValue_private (const struct KzcStringIterator *iterator)

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

KANZI_API 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

KANZI_API kzsError kzcStringCreate	(	kzUint	length,
		kzMutableString *	out_string
	)

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

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

KANZI_API kzsError kzcStringAllocate	(	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'.

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

Creates a new string of given length using specified memory manager.

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

KANZI_API kzsError kzcStringCreateEmpty ( kzMutableString * out_string )

Creates a new empty string.

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

KANZI_API kzsError kzcStringDelete ( kzMutableString string )

Deletes a string.

KANZI_API kzsError kzcStringDelete	(	KzcMemoryManager *	memoryManager,
		kzMutableString	string
	)

Deletes a string using specified memory manager.

KANZI_API 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.

KANZI_API kzBool kzcStringIsEmpty ( kzString string )

Returns KZ_TRUE if the string is empty.

KANZI_API kzsError kzcStringCopy	(	kzString	source,
		kzMutableString *	out_target
	)

Creates a copy of the given source string.

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

Creates a copy of the given source string using specified memory manager.

KANZI_API kzsError kzcStringConcatenate	(	kzString	front,
		kzString	back,
		kzMutableString *	out_string
	)

Concatenates two strings.

KANZI_API kzsError kzcStringConcatenateMultiple	(	kzUint	numStrings,
		kzMutableString *	out_string,
			...
	)

Concatenates arbitrary number of strings.

KANZI_API kzsError kzcStringSubstring	(	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.

KANZI_API 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.

KANZI_API 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.

KANZI_API kzUint kzcStringGetSubstringCount	(	kzString	string,
		kzString	pattern
	)

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

KANZI_API 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.

KANZI_API 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.

KANZI_API kzBool kzcStringStartsWith	(	kzString	string,
		kzString	pattern
	)

Checks if the given string starts with the given pattern.

KANZI_API kzBool kzcStringEndsWith	(	kzString	string,
		kzString	pattern
	)

Checks if the given string ends with the given pattern.

KANZI_API kzsError kzcStringReplace	(	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.

KANZI_API void kzcStringRemoveSubstringInPlace	(	kzMutableString	string,
		kzString	substring
	)

Remove a substring from a string in-place.

KANZI_API 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.

KANZI_API 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.

KANZI_API 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.

KANZI_API kzsError kzcIntToString	(	kzInt	value,
		kzMutableString *	out_string
	)

Returns a string representation of integer.

KANZI_API kzsError kzcFloatToString	(	kzFloat	value,
		kzMutableString *	out_string
	)

Returns an approximate string representation of a floating point value.

KANZI_API kzsError kzcStringSplit	(	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. The returned string array must be released with delete[].

KANZI_API kzsError kzcStringJoin	(	kzUint	stringCount,
		const kzString *	strings,
		kzString	delimiter,
		kzMutableString *	out_string
	)

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

KANZI_API kzsError kzcStringAsciiToLowerCase	(	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.

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

Get the formatted length of the string.

KANZI_API kzsError kzcStringFormatList	(	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.

KANZI_API kzsError kzcStringFormat	(	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).

KANZI_API kzInt kzcStringCompare	(	kzString	first,
		kzString	second
	)

Compare two strings.

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

KANZI_API 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.

KANZI_API 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.

KANZI_API 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.

KANZI_API kzBool kzcStringIsEqual	(	kzString	first,
		kzString	second
	)

Compare two strings.

Return KZ_TRUE if the strings are equal.

KANZI_API kzUint kzcStringGetUnicodeLength ( kzString string )

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

KANZI_API 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.

KANZI_API 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.

KANZI_API 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.

KANZI_API kzsError kzcStringFromUnicodeArray	(	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().

KANZI_API struct KzcStringIterator kzcStringGetIterator ( kzString string )

Get unicode iterator for given UTF-8 string.

KANZI_API kzBool kzcStringIterate_private ( struct KzcStringIterator * iterator )

See also: kzcStringIterate

KANZI_API kzUnicodeChar kzcStringIteratorGetValue_private ( const struct KzcStringIterator * iterator )

See also: kzcStringIteratorGetValue

KANZI_API kzBool kzcStringAsciiCharIsSpace ( kzChar character )

Test whether or not a certain character is whitespace.

KANZI_API kzMutableString kzcStringTrim ( kzMutableString input )

In-place string trim.

Modifies the source string.

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation