ezStringView represent a read-only sub-string of a larger string, as it can store a dedicated string end position. It derives from ezStringBase and thus provides a large set of functions for search and comparisons. More...

#include <StringView.h>

Inheritance diagram for ezStringView:

[legend]

Public Types
using	iterator = ezStringIterator

using	const_iterator = ezStringIterator

using	reverse_iterator = ezStringReverseIterator

using	const_reverse_iterator = ezStringReverseIterator

Public Member Functions
	EZ_DECLARE_POD_TYPE ()

constexpr	ezStringView ()
	Default constructor creates an invalid view.

	ezStringView (char *pStart)
	Creates a string view starting at the given position, ending at the next '\0' terminator.

template<typename T >
constexpr	ezStringView (T pStart, typename std::enable_if< std::is_same< T, const char * >::value, int >::type *=0)
	Creates a string view starting at the given position, ending at the next '\0' terminator.

template<typename T >
constexpr EZ_ALWAYS_INLINE	ezStringView (const T &&str, typename std::enable_if< std::is_same< T, const char * >::value==false &&std::is_convertible< T, const char * >::value, int >::type *=0)
	Creates a string view from any class / struct which is implicitly convertible to const char *.

constexpr	ezStringView (const char pStart, const char pEnd)
	Creates a string view for the range from pStart to pEnd.

constexpr	ezStringView (const char *pStart, ezUInt32 uiLength)
	Creates a string view for the range from pStart to pStart + uiLength.

template<size_t N>
constexpr	ezStringView (const char(&str)[N])
	Construct a string view from a string literal.

template<size_t N>
constexpr	ezStringView (char(&str)[N])
	Construct a string view from a fixed size buffer.

void	operator++ ()
	Advances the start to the next character, unless the end of the range was reached.

void	operator+= (ezUInt32 d)
	Advances the start forwards by d characters. Does not move it beyond the range's end.

ezUInt32	GetCharacter () const
	Returns the first pointed to character in Utf32 encoding.

bool	IsValid () const
	Returns true, if the current string pointed to is non empty.

const char *	GetData (ezStringBuilder &ref_sTempStorage) const
	Returns the data as a zero-terminated string. More...

ezUInt32	GetElementCount () const
	Returns the number of bytes from the start position up to its end. More...

void	SetStartPosition (const char *szCurPos)
	Allows to set the start position to a different value. More...

const char *	GetStartPointer () const
	Returns the start of the view range. More...

const char *	GetEndPointer () const
	Returns the end of the view range. This will point to the byte AFTER the last character. More...

bool	IsEmpty () const
	Returns whether the string is an empty string.

bool	IsEqual (ezStringView sOther) const
	Compares this string view with the other string view for equality.

bool	IsEqual_NoCase (ezStringView sOther) const
	Compares this string view with the other string view for equality.

bool	IsEqualN (ezStringView sOther, ezUInt32 uiCharsToCompare) const
	Compares up to a given number of characters of this string with the other string for equality. Case insensitive.

bool	IsEqualN_NoCase (ezStringView sOther, ezUInt32 uiCharsToCompare) const
	Compares up to a given number of characters of this string with the other string for equality. Case insensitive.

ezInt32	Compare (ezStringView sOther) const
	Compares this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise.

ezInt32	CompareN (ezStringView sOther, ezUInt32 uiCharsToCompare) const

ezInt32	Compare_NoCase (ezStringView sOther) 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 (ezStringView sOther, ezUInt32 uiCharsToCompare) const

bool	StartsWith (ezStringView sStartsWith) const
	Returns true, if this string starts with the given string.

bool	StartsWith_NoCase (ezStringView sStartsWith) const
	Returns true, if this string starts with the given string. Case insensitive.

bool	EndsWith (ezStringView sEndsWith) const
	Returns true, if this string ends with the given string.

bool	EndsWith_NoCase (ezStringView sEndsWith) const
	Returns true, if this string ends with the given string. 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.

const char *	FindSubString (ezStringView sStringToFind, const char *szStartSearchAt=nullptr) const

const char *	FindSubString_NoCase (ezStringView sStringToFind, const char *szStartSearchAt=nullptr) const

const char *	FindLastSubString (ezStringView sStringToFind, const char *szStartSearchAt=nullptr) const

const char *	FindLastSubString_NoCase (ezStringView sStringToFind, const char *szStartSearchAt=nullptr) const

const char *	FindWholeWord (const char szSearchFor, ezStringUtils::EZ_CHARACTER_FILTER isDelimiterCB, const char szStartSearchAt=nullptr) const

const char *	FindWholeWord_NoCase (const char szSearchFor, ezStringUtils::EZ_CHARACTER_FILTER isDelimiterCB, const char szStartSearchAt=nullptr) const

void	Shrink (ezUInt32 uiShrinkCharsFront, ezUInt32 uiShrinkCharsBack)
	Shrinks the view range by uiShrinkCharsFront characters at the front and by uiShrinkCharsBack characters at the back. More...

ezStringView	GetShrunk (ezUInt32 uiShrinkCharsFront, ezUInt32 uiShrinkCharsBack=0) const
	Returns a sub-string that is shrunk at the start and front by the given amount of characters (not bytes!).

ezStringView	GetSubString (ezUInt32 uiFirstCharacter, ezUInt32 uiNumCharacters) const
	Returns a sub-string starting at a given character (not byte offset!) and including a number of characters (not bytes). More...

void	ChopAwayFirstCharacterUtf8 ()
	Identical to 'Shrink(1, 0)' in functionality, but slightly more efficient.

void	ChopAwayFirstCharacterAscii ()
	Similar to ChopAwayFirstCharacterUtf8(), but assumes that the first character is ASCII and thus exactly one byte in length. Asserts that this is the case. More efficient than ChopAwayFirstCharacterUtf8(), if it is known that the first character is ASCII.

void	Trim (const char *szTrimChars=" \f\n\r\t\v")
	Removes all characters from the start and end that appear in the given strings by adjusting the begin and end of the view.

void	Trim (const char szTrimCharsStart, const char szTrimCharsEnd)
	Removes all characters from the start and/or end that appear in the given strings by adjusting the begin and end of the view.

bool	TrimWordStart (ezStringView sWord)
	If the string starts with the given word (case insensitive), it is removed and the function returns true.

bool	TrimWordEnd (ezStringView sWord)
	If the string ends with the given word (case insensitive), it is removed and the function returns true.

template<typename Container >
void	Split (bool bReturnEmptyStrings, Container &ref_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.

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

bool	HasAnyExtension () const
	Checks whether the given path has any file extension.

bool	HasExtension (ezStringView sExtension) const
	Checks whether the given path ends with the given extension. szExtension may start with a '.', but doesn't have to. More...

ezStringView	GetFileExtension (bool bFullExtension=false) const
	Returns the file extension of the given path. Will be empty, if the path does not end with a proper extension. More...

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.

bool	IsRootedPath () const
	Returns true, if the given path represents a 'rooted' path. See ezFileSystem for details.

ezStringView	GetRootedPathRootName () const
	Extracts the root name from a rooted path. More...

template<typename T >
constexpr EZ_ALWAYS_INLINE	ezStringView (T pStart, typename std::enable_if< std::is_same< T, const char * >::value, int >::type *)

template<size_t N>
constexpr EZ_ALWAYS_INLINE	ezStringView (const char(&str)[N])

template<size_t N>
constexpr EZ_ALWAYS_INLINE	ezStringView (char(&str)[N])

Detailed Description

ezStringView represent a read-only sub-string of a larger string, as it can store a dedicated string end position. It derives from ezStringBase and thus provides a large set of functions for search and comparisons.

Attention: ezStringView does not store string data itself. It only stores pointers into memory. For example, when you get an ezStringView to an ezStringBuilder, the ezStringView instance will point to the exact same memory, enabling you to iterate over it (read-only). That means that an ezStringView is only valid as long as its source data is not modified. Once you make any kind of modification to the source data, you should not continue using the ezStringView to that data anymore, as it might now point into invalid memory.

Member Function Documentation

◆ CompareN()

ezInt32 ezStringView::CompareN	(	ezStringView	sOther,
		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.

◆ CompareN_NoCase()

ezInt32 ezStringView::CompareN_NoCase	(	ezStringView	sOther,
		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.

◆ FindLastSubString()

const char * ezStringView::FindLastSubString	(	ezStringView	sStringToFind,
		const char *	szStartSearchAt = `nullptr`
	)		const

Returns a pointer to the last occurrence of szStringToFind, or nullptr if none was found. szStartSearchAt allows to start searching at the end of the string (if it is nullptr) or at an earlier position.

◆ FindLastSubString_NoCase()

const char * ezStringView::FindLastSubString_NoCase	(	ezStringView	sStringToFind,
		const char *	szStartSearchAt = `nullptr`
	)		const

Returns a pointer to the last occurrence of szStringToFind, or nullptr if none was found. Case insensitive. szStartSearchAt allows to start searching at the end of the string (if it is nullptr) or at an earlier position.

◆ FindSubString()

const char * ezStringView::FindSubString	(	ezStringView	sStringToFind,
		const char *	szStartSearchAt = `nullptr`
	)		const

Returns a pointer to the first occurrence of szStringToFind, or nullptr if none was found. To find the next occurrence, use an ezStringView which points to the next position and call FindSubString again.

◆ FindSubString_NoCase()

const char * ezStringView::FindSubString_NoCase	(	ezStringView	sStringToFind,
		const char *	szStartSearchAt = `nullptr`
	)		const

Returns a pointer to the first occurrence of szStringToFind, or nullptr if none was found. Case insensitive. To find the next occurrence, use an ezStringView which points to the next position and call FindSubString again.

◆ FindWholeWord()

const char * ezStringView::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.

◆ FindWholeWord_NoCase()

const char * ezStringView::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.

◆ GetData()

const char * ezStringView::GetData ( ezStringBuilder & ref_sTempStorage ) const

Returns the data as a zero-terminated string.

The string will be copied to tempStorage and the pointer to that is returned. If you really need the raw pointer to the ezStringView memory or are absolutely certain that the view points to a zero-terminated string, you can use GetStartPointer()

◆ GetElementCount()

ezUInt32 ezStringView::GetElementCount ( ) const

inline

Returns the number of bytes from the start position up to its end.

Note: Note that the element count (bytes) may be larger than the number of characters in that string, due to Utf8 encoding.

◆ GetEndPointer()

const char* ezStringView::GetEndPointer ( ) const

inline

Returns the end of the view range. This will point to the byte AFTER the last character.

That means it might point to the '\0' terminator, UNLESS the view only represents a sub-string of a larger string. Accessing the value at 'GetEnd' has therefore no real use.

◆ GetFileDirectory()

ezStringView ezStringView::GetFileDirectory ( ) const

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" -> "/"

◆ GetFileExtension()

ezStringView ezStringView::GetFileExtension ( bool bFullExtension = false ) const

Returns the file extension of the given path. Will be empty, if the path does not end with a proper extension.

If bFullExtension is false, a file named "file.a.b.c" will return "c". If bFullExtension is true, a file named "file.a.b.c" will return "a.b.c".

◆ GetFileName()

ezStringView ezStringView::GetFileName ( ) const

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.

◆ GetFileNameAndExtension()

ezStringView ezStringView::GetFileNameAndExtension ( ) const

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.

◆ GetIteratorBack()

ezStringView::reverse_iterator ezStringView::GetIteratorBack ( ) const

Returns an iterator to this string, which points to the very last character (NOT the end).

Note that this iterator will only be valid as long as this string lives. Once the original string is destroyed, all iterators to them will point into invalid memory.

◆ GetIteratorFront()

ezStringView::iterator ezStringView::GetIteratorFront ( ) const

Returns an iterator to this string, which points to the very first character.

Note that this iterator will only be valid as long as this string lives. Once the original string is destroyed, all iterators to them will point into invalid memory.

◆ GetRootedPathRootName()

ezStringView ezStringView::GetRootedPathRootName ( ) const

Extracts the root name from a rooted path.

":MyRoot" -> "MyRoot" ":MyRoot\folder" -> "MyRoot" ":\MyRoot\folder" -> "MyRoot" ":/MyRoot\folder" -> "MyRoot" Returns an empty string, if the path is not rooted.

◆ GetStartPointer()

const char* ezStringView::GetStartPointer ( ) const

inline

Returns the start of the view range.

Note: Be careful to not use this and assume the view will be zero-terminated. Use GetData(ezStringBuilder&) instead to be safe.

◆ GetSubString()

ezStringView ezStringView::GetSubString	(	ezUInt32	uiFirstCharacter,
		ezUInt32	uiNumCharacters
	)		const

Returns a sub-string starting at a given character (not byte offset!) and including a number of characters (not bytes).

If this is a Utf-8 string, the correct number of bytes are skipped to reach the given character. If you instead want to construct a sub-string from byte offsets, use the ezStringView constructor that takes a start pointer like so: ezStringView subString(this->GetStartPointer() + byteOffset, byteCount);

◆ HasExtension()

bool ezStringView::HasExtension ( ezStringView sExtension ) const

Checks whether the given path ends with the given extension. szExtension may start with a '.', but doesn't have to.

The check is case insensitive.

◆ SetStartPosition()

EZ_ALWAYS_INLINE void ezStringView::SetStartPosition ( const char * szCurPos )

Allows to set the start position to a different value.

Must be between the current start and end range.

◆ Shrink()

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

Shrinks the view range by uiShrinkCharsFront characters at the front and by uiShrinkCharsBack characters at the back.

Thus reduces the range of the view to a smaller sub-string. The current position is clamped to the new start of the range. The new end position is clamped to the new start of the range. If more characters are removed from the range, than it actually contains, the view range will become 'empty' and its state will be set to invalid, however no error or assert will be triggered.

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

/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Strings/StringView.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Strings/Implementation/StringView.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Strings/Implementation/StringView_inl.h

Public Types

Public Member Functions

Detailed Description

Member Function Documentation

◆ CompareN()

◆ CompareN_NoCase()

◆ FindLastSubString()

◆ FindLastSubString_NoCase()

◆ FindSubString()

◆ FindSubString_NoCase()

◆ FindWholeWord()

◆ FindWholeWord_NoCase()

◆ GetData()

◆ GetElementCount()

◆ GetEndPointer()

◆ GetFileDirectory()

◆ GetFileExtension()

◆ GetFileName()

◆ GetFileNameAndExtension()

◆ GetIteratorBack()

◆ GetIteratorFront()

◆ GetRootedPathRootName()

◆ GetStartPointer()

◆ GetSubString()

◆ HasExtension()

◆ SetStartPosition()

◆ Shrink()