![]() |
ezEngine
Release 25.03
|
Helper functions to work with UTF-8 strings (which include pure ASCII strings) More...
#include <StringUtils.h>
Public Types | |
using | EZ_CHARACTER_FILTER = bool(*)(ezUInt32 uiChar) |
Function Definition for a function that determines whether a (Utf32) character belongs to a certain category of characters. | |
Static Public Member Functions | |
template<typename T > | |
static constexpr bool | IsNullOrEmpty (const T *pString) |
Returns true, if the given string is a nullptr pointer or a string that immediately terminates with a '\0' character. | |
template<typename T > | |
static bool | IsNullOrEmpty (const T *pString, const T *pStringEnd) |
Returns true, if the given string is a nullptr pointer, is equal to its end or a string that immediately terminates with a '\0' character. | |
template<typename T > | |
static void | UpdateStringEnd (const T *pStringStart, const T *&ref_pStringEnd) |
Recomputes the end pointer of a string (szStringEnd), if that is currently set to ezMaxStringEnd. Otherwise does nothing. | |
template<typename T > | |
static constexpr ezUInt32 | GetStringElementCount (const T *pString) |
Returns the number of elements of type T that the string contains, until it hits an element that is zero OR until it hits the end pointer. More... | |
template<typename T > | |
static ezUInt32 | GetStringElementCount (const T *pString, const T *pStringEnd) |
Returns the number of elements of type T that the string contains, until it hits an element that is zero OR until it hits the end pointer. More... | |
static ezUInt32 | GetCharacterCount (const char *szUtf8, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns the number of characters (not Bytes!) in a Utf8 string (excluding the zero terminator), until it hits zero or the end pointer. | |
static void | GetCharacterAndElementCount (const char *szUtf8, ezUInt32 &ref_uiCharacterCount, ezUInt32 &ref_uiElementCount, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns both the number of characters and the number of bytes in a Utf8 string, until it hits zero or the end pointer. | |
static ezUInt32 | Copy (char *szDest, ezUInt32 uiDstSize, const char *szSource, const char *pSourceEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Copies the string from szSource into the given buffer, which can hold at least uiDstSize bytes. More... | |
static ezUInt32 | CopyN (char *szDest, ezUInt32 uiDstSize, const char *szSource, ezUInt32 uiCharsToCopy, const char *pSourceEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Copies up to uiCharsToCopy characters into the given buffer, which can hold at least uiDstSize bytes. More... | |
static ezUInt32 | ToUpperChar (ezUInt32 uiChar) |
Returns the upper case code point for uiChar. | |
static ezUInt32 | ToLowerChar (ezUInt32 uiChar) |
Returns the lower case code point for uiChar. | |
static ezUInt32 | ToUpperString (char *szString, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Converts a (UTF-8) string in-place to upper case. More... | |
static ezUInt32 | ToLowerString (char *szString, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Converts a (UTF-8) string in-place to lower case. More... | |
static ezInt32 | CompareChars (ezUInt32 uiCharacter1, ezUInt32 uiCharacter2) |
Compares the two code points for equality. More... | |
static ezInt32 | CompareChars (const char *szUtf8Char1, const char *szUtf8Char2) |
Compares the first character of each utf8 string for equality. More... | |
static ezInt32 | CompareChars_NoCase (ezUInt32 uiCharacter1, ezUInt32 uiCharacter2) |
Compares the two code points for equality, case-insensitive. More... | |
static ezInt32 | CompareChars_NoCase (const char *szUtf8Char1, const char *szUtf8Char2) |
Compares the first character of each utf8 string for equality, case-insensitive. More... | |
static bool | IsEqual (const char *pString1, const char *pString2, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true, if the two given strings are identical (bitwise). | |
static bool | IsEqualN (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true, if the two given strings are identical (bitwise) up to the n-th character. More... | |
static bool | IsEqual_NoCase (const char *pString1, const char *pString2, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true, if the two given strings are identical (case-insensitive). | |
static bool | IsEqualN_NoCase (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true, if the two given strings are identical (case-insensitive) up to the n-th character. More... | |
static ezInt32 | Compare (const char *pString1, const char *pString2, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Compares two strings for equality. More... | |
static ezInt32 | CompareN (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Compares the first uiCharsToCompare characters of the two strings for equality. More... | |
static ezInt32 | Compare_NoCase (const char *pString1, const char *pString2, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Compares two strings for equality, case-insensitive. More... | |
static ezInt32 | CompareN_NoCase (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *pString2End=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Compares the first uiCharsToCompare characters of the two strings for equality, case-insensitive. More... | |
static ezInt32 | snprintf (char *szDst, ezUInt32 uiDstSize, const char *szFormat,...) |
Creates a formated string in szDst. uiDstSize defines how many bytes szDst can hold. More... | |
static ezInt32 | vsnprintf (char *szDst, ezUInt32 uiDstSize, const char *szFormat, va_list szAp) |
Creates a formated string in szDst. uiDstSize defines how many bytes szDst can hold. More... | |
static bool | StartsWith (const char *szString, const char *szStartsWith, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szStartsWithEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true if szString starts with the string given in szStartsWith. | |
static bool | StartsWith_NoCase (const char *szString, const char *szStartsWith, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szStartsWithEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true if szString starts with the string given in szStartsWith. Ignores case. | |
static bool | EndsWith (const char *szString, const char *szEndsWith, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szEndsWithEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true if szString ends with the string given in szEndsWith. | |
static bool | EndsWith_NoCase (const char *szString, const char *szEndsWith, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szEndsWithEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Returns true if szString ends with the string given in szEndsWith. Ignores case. | |
static const char * | FindSubString (const char *szSource, const char *szStringToFind, const char *pSourceEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szStringToFindEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Searches for the first occurrence of szStringToFind in szSource. | |
static const char * | FindSubString_NoCase (const char *szSource, const char *szStringToFind, const char *pSourceEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szStringToFindEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Searches for the first occurrence of szStringToFind in szSource. Ignores case. | |
static const char * | FindLastSubString (const char *szSource, const char *szStringToFind, const char *szStartSearchAt=nullptr, const char *pSourceEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szStringToFindEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Searches for the last occurrence of szStringToFind in szSource before szStartSearchAt. | |
static const char * | FindLastSubString_NoCase (const char *szSource, const char *szStringToFind, const char *szStartSearchAt=nullptr, const char *pSourceEnd=ezUnicodeUtils::GetMaxStringEnd< char >(), const char *szStringToFindEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Searches for the last occurrence of szStringToFind in szSource before szStartSearchAt. Ignores case. | |
static const char * | SkipCharacters (const char *szString, EZ_CHARACTER_FILTER skipCharacterCB, bool bAlwaysSkipFirst=false) |
Starts at szString and advances to the next character for which SkipCharacterCB returns false;. More... | |
static const char * | FindWordEnd (const char *szString, EZ_CHARACTER_FILTER isDelimiterCB, bool bAlwaysSkipFirst=true) |
Returns the position in szString at which IsDelimiterCB returns true. More... | |
static void | Trim (const char *&ref_pString, const char *&ref_pStringEnd, const char *szTrimCharsStart, const char *szTrimCharsEnd) |
Removes all characters at the start and end of the string that match the respective characters and updates the new start and end of the string. More... | |
static bool | IsWhiteSpace (ezUInt32 uiChar) |
A default word delimiter function that returns true for ' ' (space), '\r' (carriage return), ' ' (newline), '\t' (tab) and '\v' (vertical tab) | |
static bool | IsDecimalDigit (ezUInt32 uiChar) |
A decimal digit from 0..9. | |
static bool | IsHexDigit (ezUInt32 uiChar) |
A hexadecimal digit from 0..F. | |
static bool | IsWordDelimiter_English (ezUInt32 uiChar) |
A default word delimiter function for English text. | |
static bool | IsIdentifierDelimiter_C_Code (ezUInt32 uiChar) |
A default word delimiter function for identifiers in C code. | |
static bool | IsValidIdentifierName (const char *pString, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Checks whether the given string is a valid identifier name in C code, ie has no white-spaces, starts with a literal etc. | |
static const char * | FindWholeWord (const char *szString, const char *szSearchFor, EZ_CHARACTER_FILTER isDelimiterCB, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Searches szString for the word szSearchFor. If IsDelimiterCB returns true for both characters in front and back of the word, the position is returned. Otherwise nullptr. | |
static const char * | FindWholeWord_NoCase (const char *szString, const char *szSearchFor, EZ_CHARACTER_FILTER isDelimiterCB, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Searches szString for the word szSearchFor. If IsDelimiterCB returns true for both characters in front and back of the word, the position is returned. Otherwise nullptr. Ignores case. | |
static ezResult | FindUIntAtTheEnd (const char *szString, ezUInt32 &out_uiValue, ezUInt32 *pStringLengthBeforeUInt=nullptr) |
Checks if the given szString ends with an unsigned integer (e.g. "MyString123"). If pStringLengthBeforeUInt is non-null the string length up to the first digit is stored. Returns EZ_SUCCESS if there is a value at the end of string, EZ_FAILURE otherwise. | |
static void | OutputFormattedInt (char *szOutputBuffer, ezUInt32 uiBufferSize, ezUInt32 &ref_uiWritePos, ezInt64 value, ezUInt8 uiWidth, bool bPadZeros, ezUInt8 uiBase) |
[internal] Prefer to use snprintf. | |
static void | OutputFormattedUInt (char *szOutputBuffer, ezUInt32 uiBufferSize, ezUInt32 &ref_uiWritePos, ezUInt64 value, ezUInt8 uiWidth, bool bPadZeros, ezUInt8 uiBase, bool bUpperCase) |
[internal] Prefer to use snprintf. | |
static void | OutputFormattedFloat (char *szOutputBuffer, ezUInt32 uiBufferSize, ezUInt32 &ref_uiWritePos, double value, ezUInt8 uiWidth, bool bPadZeros, ezInt8 iPrecision, bool bScientific, bool bRemoveTrailingZeroes=false) |
[internal] Prefer to use snprintf. | |
static ezUInt32 | CalculateLineNumber (const char *szString, const char *szOffset, const char *pStringEnd=ezUnicodeUtils::GetMaxStringEnd< char >()) |
Calculates in which line number szOffset is in the given string. More... | |
Helper functions to work with UTF-8 strings (which include pure ASCII strings)
|
static |
Calculates in which line number szOffset is in the given string.
Line numbers are 1-based. Returns 0, if szOffset is outside the given string.
|
static |
Compares two strings for equality.
Returns a negative number if the pString1 is 'smaller' or shorter than pString2. Returns a positive number, if pString1 is 'larger' or longer than pString1. Returns 0 for equal strings. Works with UTF-8 strings as well.
|
static |
Compares two strings for equality, case-insensitive.
Returns a negative number if the pString1 is 'smaller' or shorter than pString2. Returns a positive number, if pString1 is 'larger' or longer than pString1. Returns 0 for equal strings. Works with UTF-8 strings as well.
|
inlinestatic |
Compares the first character of each utf8 string for equality.
Returns a negative number, if szUtf8Char1 is smaller than szUtf8Char2. Returns a positive number, if szUtf8Char1 is larger than szUtf8Char2. Returns 0 if both are equal.
|
static |
Compares the two code points for equality.
Returns a negative number, if uiCharacter1 is smaller than uiCharacter2. Returns a positive number, if uiCharacter1 is larger than uiCharacter2. Returns 0 if both are equal.
|
inlinestatic |
Compares the first character of each utf8 string for equality, case-insensitive.
Returns a negative number, if szUtf8Char1 is smaller than szUtf8Char2. Returns a positive number, if szUtf8Char1 is larger than szUtf8Char2. Returns 0 if both are equal.
|
inlinestatic |
Compares the two code points for equality, case-insensitive.
Returns a negative number, if uiCharacter1 is smaller than uiCharacter2. Returns a positive number, if uiCharacter1 is larger than uiCharacter2. Returns 0 if both are equal.
|
static |
Compares the first uiCharsToCompare characters of the two strings for equality.
Returns a negative number if the pString1 is 'smaller' or shorter than pString2. Returns a positive number, if pString1 is 'larger' or longer than pString1. Returns 0 for equal strings. Works with UTF-8 strings as well.
|
static |
Compares the first uiCharsToCompare characters of the two strings for equality, case-insensitive.
Returns a negative number if the pString1 is 'smaller' or shorter than pString2. Returns a positive number, if pString1 is 'larger' or longer than pString1. Returns 0 for equal strings. Works with UTF-8 strings as well.
|
static |
Copies the string from szSource into the given buffer, which can hold at least uiDstSize bytes.
The string will always be \0 terminated. Multi-byte UTF-8 characters will only be copied, if they can fit completely into szDest. I.e. they will be truncated at a character boundary. Returns the number of bytes that were copied into szDest, excluding the terminating \0
|
static |
Copies up to uiCharsToCopy characters into the given buffer, which can hold at least uiDstSize bytes.
The string will always be \0 terminated. Multi-byte UTF-8 characters will only be copied, if they can fit completely into szDest. I.e. they will be truncated at a character boundary. Returns the number of bytes that were copied into szDest, excluding the terminating \0
|
static |
Returns the position in szString at which IsDelimiterCB returns true.
This is basically the inverse of SkipCharacters. SkipCharacters advances over all characters that fulfill the filter, FindWordEnd advances over all characters that do not fulfill it.
|
staticconstexpr |
Returns the number of elements of type T that the string contains, until it hits an element that is zero OR until it hits the end pointer.
Equal to the string length, if used with pure ASCII strings. Equal to the amount of bytes in a string, if used on non-ASCII (i.e. UTF-8) strings. Equal to the number of characters in a string, if used with UTF-32 strings.
|
static |
Returns the number of elements of type T that the string contains, until it hits an element that is zero OR until it hits the end pointer.
Equal to the string length, if used with pure ASCII strings. Equal to the amount of bytes in a string, if used on non-ASCII (i.e. UTF-8) strings. Equal to the number of characters in a string, if used with UTF-32 strings.
|
static |
Returns true, if the two given strings are identical (bitwise) up to the n-th character.
This function will handle UTF-8 strings properly.
|
static |
Returns true, if the two given strings are identical (case-insensitive) up to the n-th character.
This function will handle UTF-8 strings properly.
|
static |
Starts at szString and advances to the next character for which SkipCharacterCB returns false;.
If bAlwaysSkipFirst is false and szString points to a character that does not fulfill the filter, this function will return immediately and nothing will change. If bAlwaysSkipFirst is true, the first character will always be skipped, regardless what it is (unless it is the zero terminator). The latter is useful to skip an entire word and get to the next word in a string.
|
static |
Creates a formated string in szDst. uiDstSize defines how many bytes szDst can hold.
Returns the number of bytes that would have been required to output the entire string (excluding the 0 terminator).
Returns -1 if an error occurred. In this case it might also write a more detailed error message to the destination string itself. szDst may be nullptr.
uiDstSize may be zero.
This can be used to query how much storage is required, then allocate it and call snprintf again to fill it.
Formatting works exactly like printf, except that it additionally supports outputting binary with the 'b' modifier and it will output float NaN and Infinity as proper text.
|
static |
Converts a (UTF-8) string in-place to lower case.
Returns the new string length in bytes (it might shrink, but never grow), excluding the \0 terminator.
|
static |
Converts a (UTF-8) string in-place to upper case.
Returns the new string length in bytes (it might shrink, but never grow), excluding the \0 terminator.
|
static |
Removes all characters at the start and end of the string that match the respective characters and updates the new start and end of the string.
pString | The string to trim. |
pStringEnd | The end pointer into pString, either the end pointer for the not zero terminated string or ezMaxStringEnd for zero terminated ones. |
szTrimCharsStart | A string compromised of characters to trim from the start of the string. |
szTrimCharsEnd | A string compromised of characters to trim from the end of the string. |
|
static |
Creates a formated string in szDst. uiDstSize defines how many bytes szDst can hold.
Returns the number of bytes that would have been required to output the entire string (excluding the 0 terminator).
Returns -1 if an error occurred. In this case it might also write a more detailed error message to the destination string itself. szDst may be nullptr.
uiDstSize may be zero.
This can be used to query how much storage is required, then allocate it and call snprintf again to fill it.
Formatting works exactly like printf, except that it additionally supports outputting binary with the 'b' modifier and it will output float NaN and Infinity as proper text.