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

#include <StringView.h>

Inheritance diagram for plStringView:

[legend]

Public Types
using	iterator = plStringIterator

using	const_iterator = plStringIterator

using	reverse_iterator = plStringReverseIterator

using	const_reverse_iterator = plStringReverseIterator

Public Member Functions
	PL_DECLARE_POD_TYPE ()

constexpr	plStringView ()
	Default constructor creates an invalid view.

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

template<typename T >
constexpr	plStringView (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 PL_ALWAYS_INLINE	plStringView (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	plStringView (const char pStart, const char pEnd)
	Creates a string view for the range from pStart to pEnd.

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

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

template<size_t N>
constexpr	plStringView (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+= (plUInt32 d)
	Advances the start forwards by d characters. Does not move it beyond the range's end.

plUInt32	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 (plStringBuilder &ref_sTempStorage) const
	Returns the data as a zero-terminated string.

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

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

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

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

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

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

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

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

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

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

plInt32	CompareN (plStringView sOther, plUInt32 uiCharsToCompare) const

plInt32	Compare_NoCase (plStringView sOther) const
	Compares this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise. Case insensitive.

plInt32	CompareN_NoCase (plStringView sOther, plUInt32 uiCharsToCompare) const

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

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

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

bool	EndsWith_NoCase (plStringView sEndsWith) const
	Returns true, if this string ends with the given string. Case insensitive.

const char *	ComputeCharacterPosition (plUInt32 uiCharacterIndex) const
	Computes the pointer to the n-th character in the string. This is a linear search from the start.

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

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

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

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

const char *	FindWholeWord (const char szSearchFor, plStringUtils::PL_CHARACTER_FILTER isDelimiterCB, const char szStartSearchAt=nullptr) const

const char *	FindWholeWord_NoCase (const char szSearchFor, plStringUtils::PL_CHARACTER_FILTER isDelimiterCB, const char szStartSearchAt=nullptr) const

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

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

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

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)
	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 (plStringView sWord)
	If the string starts with the given word (case insensitive), it is removed and the function returns true.

bool	TrimWordEnd (plStringView 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 plStringView's which represent each found substring. If bReturnEmptyStrings is true, even empty strings between separators are returned. Output must be a container that stores plStringView'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.

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

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

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

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

plStringView	GetFileName () const
	Returns the file name of a path, excluding the path and extension.

plStringView	GetFileNameAndExtension () const
	Returns the substring that represents the file name including the file extension.

plStringView	GetFileDirectory () const
	Returns the directory of the given file, which is the substring up to the last path separator.

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 plFileSystem for details.

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

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

template<size_t N>
constexpr PL_ALWAYS_INLINE	plStringView (const char(&str)[N])

template<size_t N>
constexpr PL_ALWAYS_INLINE	plStringView (char(&str)[N])

Detailed Description

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

Attention: plStringView does not store string data itself. It only stores pointers into memory. For example, when you get an plStringView to an plStringBuilder, the plStringView instance will point to the exact same memory, enabling you to iterate over it (read-only). That means that an plStringView 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 plStringView to that data anymore, as it might now point into invalid memory.

Member Function Documentation

◆ CompareN()

plInt32 plStringView::CompareN	(	plStringView	sOther,
		plUInt32	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()

plInt32 plStringView::CompareN_NoCase	(	plStringView	sOther,
		plUInt32	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 * plStringView::FindLastSubString	(	plStringView	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 * plStringView::FindLastSubString_NoCase	(	plStringView	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 * plStringView::FindSubString	(	plStringView	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 plStringView which points to the next position and call FindSubString again.

◆ FindSubString_NoCase()

const char * plStringView::FindSubString_NoCase	(	plStringView	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 plStringView which points to the next position and call FindSubString again.

◆ FindWholeWord()

const char * plStringView::FindWholeWord	(	const char *	szSearchFor,
		plStringUtils::PL_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 * plStringView::FindWholeWord_NoCase	(	const char *	szSearchFor,
		plStringUtils::PL_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 * plStringView::GetData ( plStringBuilder & 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 plStringView memory or are absolutely certain that the view points to a zero-terminated string, you can use GetStartPointer()

◆ GetElementCount()

plUInt32 plStringView::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 * plStringView::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()

plStringView plStringView::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()

plStringView plStringView::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()

plStringView plStringView::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()

plStringView plStringView::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()

plStringView::reverse_iterator plStringView::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()

plStringView::iterator plStringView::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()

plStringView plStringView::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 * plStringView::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(plStringBuilder&) instead to be safe.

◆ GetSubString()

plStringView plStringView::GetSubString	(	plUInt32	uiFirstCharacter,
		plUInt32	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 plStringView constructor that takes a start pointer like so: plStringView subString(this->GetStartPointer() + byteOffset, byteCount);

◆ HasExtension()

bool plStringView::HasExtension ( plStringView 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()

PL_ALWAYS_INLINE void plStringView::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 plStringView::Shrink	(	plUInt32	uiShrinkCharsFront,
		plUInt32	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:

Code/Engine/Foundation/Strings/StringView.h
Code/Engine/Foundation/Strings/Implementation/StringView.cpp
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()