ezEngine  Milestone 7
ezStringUtils Class Reference

Helper functions to work with UTF-8 strings (which include pure ASCII strings) More...

#include <StringUtils.h>

Public Types

typedef bool(* EZ_CHARACTER_FILTER )(ezUInt32 uiChar)
 Function Definition for a function that determines whether a (Utf32) character belongs to a certain category of characters.
 

Public Member Functions

template<typename T >
EZ_FORCE_INLINE bool IsNullOrEmpty (const T *pString)
 
template<typename T >
EZ_FORCE_INLINE bool IsNullOrEmpty (const T *pString, const T *pStringEnd)
 
template<typename T >
EZ_FORCE_INLINE void UpdateStringEnd (const T *szStringStart, const T *&szStringEnd)
 
template<typename T >
ezUInt32 GetStringElementCount (const T *pString, const T *pStringEnd)
 

Static Public Member Functions

template<typename T >
static 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 *szStringStart, const T *&szStringEnd)
 Recomputes the end pointer of a string (szStringEnd), if that is currently set to ezMaxStringEnd. Otherwise does nothing.
 
template<typename T >
static ezUInt32 GetStringElementCount (const T *pString, const T *pStringEnd=(const T *)-1)
 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=ezMaxStringEnd)
 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 &uiCharacterCount, ezUInt32 &uiElementCount, const char *pStringEnd=ezMaxStringEnd)
 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=ezMaxStringEnd)
 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=ezMaxStringEnd)
 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)
 Converts a (UTF-8) string in-place to upper case. More...
 
static ezUInt32 ToLowerString (char *szString)
 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=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 Returns true, if the two given strings are identical (bitwise).
 
static bool IsEqualN (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 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=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 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=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 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=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 Compares two strings for equality. More...
 
static ezInt32 CompareN (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 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=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 Compares two strings for equality, case-insensitive. More...
 
static ezInt32 CompareN_NoCase (const char *pString1, const char *pString2, ezUInt32 uiCharsToCompare, const char *pString1End=ezMaxStringEnd, const char *pString2End=ezMaxStringEnd)
 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 ap)
 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=ezMaxStringEnd, const char *szStartsWithEnd=ezMaxStringEnd)
 Returns true if szString starts with the string given in szStartsWith.
 
static bool StartsWith_NoCase (const char *szString, const char *szStartsWith, const char *pStringEnd=ezMaxStringEnd, const char *szStartsWithEnd=ezMaxStringEnd)
 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=ezMaxStringEnd, const char *szEndsWithEnd=ezMaxStringEnd)
 Returns true if szString ends with the string given in szEndsWith.
 
static bool EndsWith_NoCase (const char *szString, const char *szEndsWith, const char *pStringEnd=ezMaxStringEnd, const char *szEndsWithEnd=ezMaxStringEnd)
 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=ezMaxStringEnd)
 Searches for the first occurrence of szStringToFind in szSource.
 
static const char * FindSubString_NoCase (const char *szSource, const char *szStringToFind, const char *pSourceEnd=ezMaxStringEnd)
 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=ezMaxStringEnd)
 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=ezMaxStringEnd)
 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 *&pString, const char *&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), '' (carriage return), '
' (newline), '' (tab) and '' (vertical tab)
 
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 const char * FindWholeWord (const char *szString, const char *szSearchFor, EZ_CHARACTER_FILTER IsDelimiterCB, const char *pStringEnd=ezMaxStringEnd)
 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=ezMaxStringEnd)
 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 EZ_FORCE_INLINE void AddUsedStringLength (ezUInt32 uiLength)
 
static EZ_FORCE_INLINE void PrintStringLengthStatistics ()
 

Detailed Description

Helper functions to work with UTF-8 strings (which include pure ASCII strings)

Member Function Documentation

ezInt32 ezStringUtils::Compare ( const char *  pString1,
const char *  pString2,
const char *  pString1End = ezMaxStringEnd,
const char *  pString2End = ezMaxStringEnd 
)
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.

ezInt32 ezStringUtils::Compare_NoCase ( const char *  pString1,
const char *  pString2,
const char *  pString1End = ezMaxStringEnd,
const char *  pString2End = ezMaxStringEnd 
)
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.

EZ_FORCE_INLINE ezInt32 ezStringUtils::CompareChars ( ezUInt32  uiCharacter1,
ezUInt32  uiCharacter2 
)
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.

ezInt32 ezStringUtils::CompareChars ( const char *  szUtf8Char1,
const char *  szUtf8Char2 
)
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.

ezInt32 ezStringUtils::CompareChars_NoCase ( ezUInt32  uiCharacter1,
ezUInt32  uiCharacter2 
)
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.

ezInt32 ezStringUtils::CompareChars_NoCase ( const char *  szUtf8Char1,
const char *  szUtf8Char2 
)
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.

ezInt32 ezStringUtils::CompareN ( const char *  pString1,
const char *  pString2,
ezUInt32  uiCharsToCompare,
const char *  pString1End = ezMaxStringEnd,
const char *  pString2End = ezMaxStringEnd 
)
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.

ezInt32 ezStringUtils::CompareN_NoCase ( const char *  pString1,
const char *  pString2,
ezUInt32  uiCharsToCompare,
const char *  pString1End = ezMaxStringEnd,
const char *  pString2End = ezMaxStringEnd 
)
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.

ezUInt32 ezStringUtils::Copy ( char *  szDest,
ezUInt32  uiDstSize,
const char *  szSource,
const char *  pSourceEnd = ezMaxStringEnd 
)
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

ezUInt32 ezStringUtils::CopyN ( char *  szDest,
ezUInt32  uiDstSize,
const char *  szSource,
ezUInt32  uiCharsToCopy,
const char *  pSourceEnd = ezMaxStringEnd 
)
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

const char * ezStringUtils::FindWordEnd ( const char *  szString,
EZ_CHARACTER_FILTER  IsDelimiterCB,
bool  bAlwaysSkipFirst = true 
)
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.

template<typename T >
static ezUInt32 ezStringUtils::GetStringElementCount ( const T *  pString,
const T *  pStringEnd = (const T *)-1 
)
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.

EZ_FORCE_INLINE bool ezStringUtils::IsEqualN ( const char *  pString1,
const char *  pString2,
ezUInt32  uiCharsToCompare,
const char *  pString1End = ezMaxStringEnd,
const char *  pString2End = ezMaxStringEnd 
)
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.

EZ_FORCE_INLINE bool ezStringUtils::IsEqualN_NoCase ( const char *  pString1,
const char *  pString2,
ezUInt32  uiCharsToCompare,
const char *  pString1End = ezMaxStringEnd,
const char *  pString2End = ezMaxStringEnd 
)
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.

const char * ezStringUtils::SkipCharacters ( const char *  szString,
EZ_CHARACTER_FILTER  SkipCharacterCB,
bool  bAlwaysSkipFirst = false 
)
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.

int ezStringUtils::snprintf ( char *  szDst,
ezUInt32  uiDstSize,
const char *  szFormat,
  ... 
)
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.

ezUInt32 ezStringUtils::ToLowerString ( char *  szString)
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.

ezUInt32 ezStringUtils::ToUpperString ( char *  szString)
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.

void ezStringUtils::Trim ( const char *&  pString,
const char *&  pStringEnd,
const char *  szTrimCharsStart,
const char *  szTrimCharsEnd 
)
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.

Parameters
pStringThe string to trim.
pStringEndThe end pointer into pString, either the end pointer for the not zero terminated string or ezMaxStringEnd for zero terminated ones.
szTrimCharsStartA string compromised of characters to trim from the start of the string.
szTrimCharsEndA string compromised of characters to trim from the end of the string.
int ezStringUtils::vsnprintf ( char *  szDst,
ezUInt32  uiDstSize,
const char *  szFormat,
va_list  ap 
)
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.


The documentation for this class was generated from the following files: