ezEngine  Milestone 7
ezStringBuilder Class Reference

ezStringBuilder is a class that is meant for creating and modifying strings. More...

#include <StringBuilder.h>

Inheritance diagram for ezStringBuilder:

Public Member Functions

 ezStringBuilder (ezAllocatorBase *pAllocator=ezFoundation::GetDefaultAllocator())
 Initializes the string to be empty. No data is allocated, but the ezStringBuilder ALWAYS creates an array on the stack.
 
 ezStringBuilder (const ezStringBuilder &rhs)
 Copies the given string into this one.
 
 ezStringBuilder (ezStringBuilder &&rhs)
 Moves the given string into this one.
 
template<ezUInt16 Size>
 ezStringBuilder (const ezHybridStringBase< Size > &rhs)
 Copies the given string into this one.
 
template<ezUInt16 Size, typename A >
 ezStringBuilder (const ezHybridString< Size, A > &rhs)
 Copies the given string into this one.
 
template<ezUInt16 Size>
 ezStringBuilder (ezHybridStringBase< Size > &&rhs)
 Moves the given string into this one.
 
template<ezUInt16 Size, typename A >
 ezStringBuilder (ezHybridString< Size, A > &&rhs)
 Moves the given string into this one.
 
 ezStringBuilder (const char *pData1, const char *pData2, const char *pData3=nullptr, const char *pData4=nullptr, const char *pData5=nullptr, const char *pData6=nullptr)
 Constructor that appends all the given strings.
 
 ezStringBuilder (const char *szUTF8, ezAllocatorBase *pAllocator=ezFoundation::GetDefaultAllocator())
 Copies the given Utf8 string into this one.
 
 ezStringBuilder (const wchar_t *szWChar, ezAllocatorBase *pAllocator=ezFoundation::GetDefaultAllocator())
 Copies the given wchar_t string into this one.
 
 ezStringBuilder (const ezStringView &rhs, ezAllocatorBase *pAllocator=ezFoundation::GetDefaultAllocator())
 Copies the given substring into this one. The ezStringView might actually be a substring of this very string.
 
void operator= (const ezStringBuilder &rhs)
 Copies the given string into this one.
 
void operator= (ezStringBuilder &&rhs)
 Moves the given string into this one.
 
void operator= (const char *szUTF8)
 Copies the given Utf8 string into this one.
 
void operator= (const wchar_t *szWChar)
 Copies the given wchar_t string into this one.
 
void operator= (const ezStringView &rhs)
 Copies the given substring into this one. The ezStringView might actually be a substring of this very string.
 
template<ezUInt16 Size>
void operator= (const ezHybridStringBase< Size > &rhs)
 Copies the given string into this one.
 
template<ezUInt16 Size, typename A >
void operator= (const ezHybridString< Size, A > &rhs)
 Copies the given string into this one.
 
template<ezUInt16 Size>
void operator= (ezHybridStringBase< Size > &&rhs)
 Moves the given string into this one.
 
template<ezUInt16 Size, typename A >
void operator= (ezHybridString< Size, A > &&rhs)
 Moves the given string into this one.
 
ezAllocatorBaseGetAllocator () const
 Returns the allocator that is used by this object.
 
 operator ezStringView () const
 Returns a string view to this string's data.
 
 operator const char * () const
 Returns a pointer to the internal Utf8 string.
 
void Clear ()
 Resets this string to be empty. Does not deallocate any previously allocated data, as it might be reused later again.
 
const char * GetData () const
 Returns a char pointer to the internal Utf8 data.
 
ezUInt32 GetElementCount () const
 Returns the number of bytes that this string takes up.
 
ezUInt32 GetCharacterCount () const
 Returns the number of characters of which this string consists. Might be less than GetElementCount, if it contains Utf8 multi-byte characters.
 
bool IsPureASCII () const
 Returns whether this string only contains ASCII characters, which means that GetElementCount() == GetCharacterCount()
 
void ToUpper ()
 Converts all characters to upper case. Might move the string data around, so all iterators to the data will be invalid afterwards.
 
void ToLower ()
 Converts all characters to lower case. Might move the string data around, so all iterators to the data will be invalid afterwards.
 
void ChangeCharacter (iterator &it, ezUInt32 uiCharacter)
 Changes the single character in this string, to which the iterator currently points. More...
 
void Set (const char *pData1, const char *pData2=nullptr, const char *pData3=nullptr, const char *pData4=nullptr, const char *pData5=nullptr, const char *pData6=nullptr)
 Sets the string by concatenating all given strings.
 
void SetSubString_FromTo (const char *pStart, const char *pEnd)
 Copies the string starting at pStart up to pEnd (exclusive).
 
void SetSubString_ElementCount (const char *pStart, ezUInt32 uiElementCount)
 Copies the string starting at pStart with a length of uiElementCount bytes.
 
void SetSubString_CharacterCount (const char *pStart, ezUInt32 uiCharacterCount)
 Copies the string starting at pStart with a length of uiCharacterCount characters.
 
void Append (ezUInt32 uiChar)
 Appends a single Utf32 character.
 
void Append (const wchar_t *pData1, const wchar_t *pData2=nullptr, const wchar_t *pData3=nullptr, const wchar_t *pData4=nullptr, const wchar_t *pData5=nullptr, const wchar_t *pData6=nullptr)
 Appends all the given strings at the back of this string in one operation.
 
void Append (const char *pData1, const char *pData2=nullptr, const char *pData3=nullptr, const char *pData4=nullptr, const char *pData5=nullptr, const char *pData6=nullptr)
 Appends all the given strings at the back of this string in one operation.
 
void AppendFormat (const char *szUtf8Format,...)
 Appends the formatted string.
 
void AppendFormatArgs (const char *szUtf8Format, va_list args)
 Appends the formatted string.
 
void Prepend (ezUInt32 uiChar)
 Prepends a single Utf32 character.
 
void Prepend (const wchar_t *pData1, const wchar_t *pData2=nullptr, const wchar_t *pData3=nullptr, const wchar_t *pData4=nullptr, const wchar_t *pData5=nullptr, const wchar_t *pData6=nullptr)
 Prepends all the given strings to the front of this string in one operation.
 
void Prepend (const char *pData1, const char *pData2=nullptr, const char *pData3=nullptr, const char *pData4=nullptr, const char *pData5=nullptr, const char *pData6=nullptr)
 Prepends all the given strings to the front of this string in one operation.
 
void PrependFormat (const char *szUtf8Format,...)
 Prepends the formatted string.
 
void PrependFormatArgs (const char *szUtf8Format, va_list args)
 Prepends the formatted string.
 
void Format (const char *szUtf8Format,...)
 Sets this string to the formatted string.
 
void FormatArgs (const char *szUtf8Format, va_list args)
 Sets this string to the formatted string.
 
void Shrink (ezUInt32 uiShrinkCharsFront, ezUInt32 uiShrinkCharsBack)
 Removes the first n and last m characters from this string. More...
 
void Reserve (ezUInt32 uiNumElements)
 Reserves uiNumElements bytes.
 
void ReplaceSubString (const char *szStartPos, const char *szEndPos, const ezStringView &szReplaceWith)
 Replaces the string that starts at szStartPos and ends at szEndPos with the string szReplaceWith.
 
void Insert (const char *szInsertAtPos, const ezStringView &szTextToInsert)
 A wrapper around ReplaceSubString. Will insert the given string at szInsertAtPos.
 
void Remove (const char *szRemoveFromPos, const char *szRemoveToPos)
 A wrapper around ReplaceSubString. Will remove the substring which starts at szRemoveFromPos and ends at szRemoveToPos.
 
const char * ReplaceFirst (const char *szSearchFor, const ezStringView &szReplacement, const char *szStartSearchAt=nullptr)
 Replaces the first occurrence of szSearchFor by szReplacement. Optionally starts searching at szStartSearchAt (or the beginning). More...
 
const char * ReplaceFirst_NoCase (const char *szSearchFor, const ezStringView &szReplacement, const char *szStartSearchAt=nullptr)
 Case-insensitive version of ReplaceFirst.
 
const char * ReplaceLast (const char *szSearchFor, const ezStringView &szReplacement, const char *szStartSearchAt=nullptr)
 Replaces the last occurrence of szSearchFor by szReplacement. Optionally starts searching at szStartSearchAt (or the end). More...
 
const char * ReplaceLast_NoCase (const char *szSearchFor, const ezStringView &szReplacement, const char *szStartSearchAt=nullptr)
 Case-insensitive version of ReplaceLast.
 
ezUInt32 ReplaceAll (const char *szSearchFor, const ezStringView &szReplacement)
 Replaces all occurrences of szSearchFor by szReplacement. Returns the number of replacements.
 
ezUInt32 ReplaceAll_NoCase (const char *szSearchFor, const ezStringView &szReplacement)
 Case-insensitive version of ReplaceAll.
 
const char * ReplaceWholeWord (const char *szSearchFor, const ezStringView &szReplaceWith, ezStringUtils::EZ_CHARACTER_FILTER IsDelimiterCB)
 Replaces the first occurrence of szSearchFor by szReplaceWith, if szSearchFor was found to be a 'whole word', as indicated by the delimiter function IsDelimiterCB.
 
const char * ReplaceWholeWord_NoCase (const char *szSearchFor, const ezStringView &szReplaceWith, ezStringUtils::EZ_CHARACTER_FILTER IsDelimiterCB)
 Case-insensitive version of ReplaceWholeWord.
 
ezUInt32 ReplaceWholeWordAll (const char *szSearchFor, const ezStringView &szReplaceWith, ezStringUtils::EZ_CHARACTER_FILTER IsDelimiterCB)
 Replaces all occurrences of szSearchFor by szReplaceWith, if szSearchFor was found to be a 'whole word', as indicated by the delimiter function IsDelimiterCB.
 
ezUInt32 ReplaceWholeWordAll_NoCase (const char *szSearchFor, const ezStringView &szReplaceWith, ezStringUtils::EZ_CHARACTER_FILTER IsDelimiterCB)
 Case-insensitive version of ReplaceWholeWordAll.
 
template<typename Container >
void Split (bool bReturnEmptyStrings, Container &Output, const char *szSeparator1, const char *szSeparator2=nullptr, const char *szSeparator3=nullptr, const char *szSeparator4=nullptr, const char *szSeparator5=nullptr, const char *szSeparator6=nullptr) const
 Fills the given container with ezStringView's which represent each found substring. If bReturnEmptyStrings is true, even empty strings between separators are returned. Output must be a container that stores ezStringView's and provides the functions 'Clear' and 'Append'. szSeparator1 to szSeparator6 are strings which act as separators and indicate where to split the string. This string itself will not be modified.
 
void ReadAll (ezStreamReaderBase &Stream)
 Replaces the current string with the content from the stream. Reads the stream to its end.
 
bool HasAnyExtension () const
 Checks whether the given path has any file extension.
 
bool HasExtension (const char *szExtension) const
 Checks whether the given path ends with the given extension. szExtension should start with a '.' for performance reasons, but it will work without a '.' too.
 
ezStringView GetFileExtension () const
 Returns the file extension of the given path. Will be empty, if the path does not end with a proper extension.
 
ezStringView GetFileName () const
 Returns the file name of a path, excluding the path and extension. More...
 
ezStringView GetFileNameAndExtension () const
 Returns the substring that represents the file name including the file extension. More...
 
ezStringView GetFileDirectory () const
 Returns the directory of the given file, which is the substring up to the last path separator. More...
 
bool IsAbsolutePath () const
 Returns true, if the given path represents an absolute path on the current OS.
 
bool IsRelativePath () const
 Returns true, if the given path represents a relative path on the current OS.
 
void MakeCleanPath ()
 Removes "../" where possible, replaces all path separators with /, removes double slashes. More...
 
void PathParentDirectory (ezUInt32 uiLevelsUp=1)
 Modifies this string to point to the parent directory. More...
 
void AppendPath (const char *szPath1, const char *szPath2=nullptr, const char *szPath3=nullptr, const char *szPath4=nullptr)
 Appends several path pieces. Makes sure they are always properly separated by a slash. More...
 
void ChangeFileName (const char *szNewFileName)
 Changes the file name part of the path, keeps the extension intact (if there is any).
 
void ChangeFileNameAndExtension (const char *szNewFileNameWithExtension)
 Changes the file name and the extension part of the path.
 
void ChangeFileExtension (const char *szNewExtension)
 Only changes the file extension of the path. If there is no extension yet, one is appended. More...
 
void RemoveFileExtension ()
 If any extension exists, it is removed, including the dot before it.
 
void MakeRelativeTo (const char *szAbsolutePathToMakeThisRelativeTo)
 Converts this path into a relative path to the path with the awesome variable name 'szAbsolutePathToMakeThisRelativeTo'.
 
void MakePathSeparatorsNative ()
 Cleans this path up and replaces all path separators by the OS specific separator. More...
 
bool IsPathBelowFolder (const char *szPathToFolder)
 Checks whether this path is a sub-path of the given path. More...
 
ezUInt64 GetHeapMemoryUsage () const
 Returns the amount of bytes that are currently allocated on the heap.
 
void Trim (const char *szTrimChars)
 Removes all characters from the start and end that appear in the given strings.
 
void Trim (const char *szTrimCharsStart, const char *szTrimCharsEnd)
 Removes all characters from the start and/or end that appear in the given strings.
 
- Public Member Functions inherited from ezStringBase< ezStringBuilder >
bool IsEmpty () const
 Returns whether the string is an empty string.
 
bool StartsWith (const char *szStartsWith) const
 Returns true, if this string starts with the given string.
 
bool StartsWith_NoCase (const char *szStartsWith) const
 Returns true, if this string starts with the given string. Case insensitive.
 
bool EndsWith (const char *szEndsWith) const
 Returns true, if this string ends with the given string.
 
bool EndsWith_NoCase (const char *szEndsWith) const
 Returns true, if this string ends with the given string. Case insensitive.
 
const char * FindSubString (const char *szStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindSubString_NoCase (const char *szStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindLastSubString (const char *szStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindLastSubString_NoCase (const char *szStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindWholeWord (const char *szSearchFor, ezStringUtils::EZ_CHARACTER_FILTER IsDelimiterCB, const char *szStartSearchAt=nullptr) const
 Searches for the word szSearchFor. If IsDelimiterCB returns true for both characters in front and back of the word, the position is returned. Otherwise nullptr.
 
const char * FindWholeWord_NoCase (const char *szSearchFor, ezStringUtils::EZ_CHARACTER_FILTER IsDelimiterCB, const char *szStartSearchAt=nullptr) const
 Searches 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.
 
ezInt32 Compare (const char *pString2) const
 Compares this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise.
 
ezInt32 CompareN (const char *pString2, ezUInt32 uiCharsToCompare) const
 Compares up to a given number of characters of this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise.
 
ezInt32 Compare_NoCase (const char *pString2) const
 Compares this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise. Case insensitive.
 
ezInt32 CompareN_NoCase (const char *pString2, ezUInt32 uiCharsToCompare) const
 Compares up to a given number of characters of this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise. Case insensitive.
 
bool IsEqual (const char *pString2) const
 Compares this string with the other string for equality.
 
bool IsEqualN (const char *pString2, ezUInt32 uiCharsToCompare) const
 Compares up to a given number of characters of this string with the other string for equality. Case insensitive.
 
bool IsEqual_NoCase (const char *pString2) const
 Compares this string with the other string for equality.
 
bool IsEqualN_NoCase (const char *pString2, ezUInt32 uiCharsToCompare) const
 Compares up to a given number of characters of this string with the other string for equality. Case insensitive.
 
const char * ComputeCharacterPosition (ezUInt32 uiCharacterIndex) const
 Computes the pointer to the n-th character in the string. This is a linear search from the start.
 
iterator GetIteratorFront () const
 Returns an iterator to this string, which points to the very first character. More...
 
reverse_iterator GetIteratorBack () const
 Returns an iterator to this string, which points to the very last character (NOT the end). More...
 

Private Member Functions

void RemoveDoubleSlashesInPath ()
 Will remove all double path separators (slashes and backslashes) in a path, except if the path starts with two (back-)slashes, those are kept, as they might indicate a UNC path.
 
void ChangeCharacterNonASCII (iterator &it, ezUInt32 uiCharacter)
 
void AppendTerminator ()
 

Private Attributes

ezUInt32 m_uiCharacterCount
 
ezHybridArray< char, 128 > m_Data
 

Friends

template<ezUInt16 T>
class ezHybridStringBase
 

Additional Inherited Members

- Public Types inherited from ezStringBase< ezStringBuilder >
typedef ezStringIterator
< ezStringBuilder
iterator
 
typedef ezStringIterator
< ezStringBuilder
const_iterator
 
typedef
ezStringReverseIterator
< ezStringBuilder
reverse_iterator
 
typedef
ezStringReverseIterator
< ezStringBuilder
const_reverse_iterator
 

Detailed Description

ezStringBuilder is a class that is meant for creating and modifying strings.

It is not meant to store strings for a longer duration. Each ezStringBuilder uses an ezHybridArray to allocate a large buffer on the stack, such that string manipulations are possible without memory allocations, unless the string is too large. No sharing of data happens between ezStringBuilder instances, as it is expected that they will be modified anyway. Instead all data is always copied, therefore instances should not be passed by copy. All string data is stored Utf8 encoded, just as all other string classes, too. That makes it difficult to modify individual characters. Instead you should prefer high-level functions such as 'ReplaceSubString'. If individual characters must be modified, it might make more sense to create a second ezStringBuilder, and iterate over the first while rebuilding the desired result in the second. For very convenient string creation, printf functionality is also available via the 'Format', 'AppendFormat' and 'PrependFormat' functions. Once a string is built and should only be stored for read access, it should be stored in an ezString instance.

Member Function Documentation

void ezStringBuilder::AppendPath ( const char *  szPath1,
const char *  szPath2 = nullptr,
const char *  szPath3 = nullptr,
const char *  szPath4 = nullptr 
)

Appends several path pieces. Makes sure they are always properly separated by a slash.

Will call 'MakeCleanPath' internally, so the representation of the path might change.

void ezStringBuilder::ChangeCharacter ( iterator it,
ezUInt32  uiCharacter 
)
inline

Changes the single character in this string, to which the iterator currently points.

The string might need to be moved around, if its encoding size changes, however the given iterator will be adjusted so that it will always stay valid.

Note
This can be a very costly operation (unless this string is pure ASCII). It is only provided for the few rare cases where it is more convenient and performance is not of concern. If possible, do not use this function, at all.
void ezStringBuilder::ChangeFileExtension ( const char *  szNewExtension)

Only changes the file extension of the path. If there is no extension yet, one is appended.

szNewExtension must not start with a dot.

ezStringView ezStringBuilder::GetFileDirectory ( ) const
inline

Returns the directory of the given file, which is the substring up to the last path separator.

If the path already ends in a path separator, and thus points to a folder, instead of a file, the unchanged path is returned. "path/to/file" -> "path/to/" "path/to/folder/" -> "path/to/folder/" "filename" -> "" "/file_at_root_level" -> "/"

ezStringView ezStringBuilder::GetFileName ( ) const
inline

Returns the file name of a path, excluding the path and extension.

If the path already ends with a path separator, the result will be empty.

ezStringView ezStringBuilder::GetFileNameAndExtension ( ) const
inline

Returns the substring that represents the file name including the file extension.

Returns an empty string, if sPath already ends in a path separator, or is empty itself.

bool ezStringBuilder::IsPathBelowFolder ( const char *  szPathToFolder)

Checks whether this path is a sub-path of the given path.

This function will call 'MakeCleanPath' to be able to compare both paths, thus it might modify the data of this instance.

An empty folder (zero length) does not contain ANY files.
A non-existing file-name (zero length) is never in any folder.
Example:
IsFileBelowFolder ("", "XYZ") -> always false
IsFileBelowFolder ("XYZ", "") -> always false
IsFileBelowFolder ("", "") -> always false

void ezStringBuilder::MakeCleanPath ( )

Removes "../" where possible, replaces all path separators with /, removes double slashes.

All paths use slashes on all platforms. If you need to convert a path to the OS specific representation, use 'MakePathSeparatorsNative' 'MakeCleanPath' will in rare circumstances grow the string by one character. That means it is quite safe to assume that it will not waste time on memory allocations. If it is repeatedly called on the same string, it has a minor overhead for computing the same string over and over, but no memory allocations will be done (everything is in-place).

Removes all double path separators (slashes and backslashes) in a path, except if the path starts with two (back-)slashes, those are kept, as they might indicate a UNC path.

void ezStringBuilder::MakePathSeparatorsNative ( )

Cleans this path up and replaces all path separators by the OS specific separator.

This can be used, if you want to present paths in the OS specific form to the user in the UI. In all other cases the internal representation uses slashes, no matter on which operating system.

void ezStringBuilder::PathParentDirectory ( ezUInt32  uiLevelsUp = 1)

Modifies this string to point to the parent directory.

'uiLevelsUp' can be used to go several folders upwards. It has to be at least one. If there are no more folders to go up, "../" is appended as much as needed.

const char * ezStringBuilder::ReplaceFirst ( const char *  szSearchFor,
const ezStringView szReplacement,
const char *  szStartSearchAt = nullptr 
)

Replaces the first occurrence of szSearchFor by szReplacement. Optionally starts searching at szStartSearchAt (or the beginning).

Returns the first position where szSearchFor was found, or nullptr if nothing was found (and replaced).

const char * ezStringBuilder::ReplaceLast ( const char *  szSearchFor,
const ezStringView szReplacement,
const char *  szStartSearchAt = nullptr 
)

Replaces the last occurrence of szSearchFor by szReplacement. Optionally starts searching at szStartSearchAt (or the end).

Returns the last position where szSearchFor was found, or nullptr if nothing was found (and replaced).

void ezStringBuilder::Shrink ( ezUInt32  uiShrinkCharsFront,
ezUInt32  uiShrinkCharsBack 
)

Removes the first n and last m characters from this string.

This function will never reallocate data. Removing characters at the back is very cheap. Removing characters at the front needs to move data around, so can be quite costly.


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