XII Release 0.1.0
Loading...
Searching...
No Matches
xiiStringView Class Reference

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

#include <StringView.h>

Inheritance diagram for xiiStringView:
[legend]

Public Types

using iterator = xiiStringIterator
 
using const_iterator = xiiStringIterator
 
using reverse_iterator = xiiStringReverseIterator
 
using const_reverse_iterator = xiiStringReverseIterator
 

Public Member Functions

 XII_DECLARE_POD_TYPE ()
 
constexpr xiiStringView ()
 Default constructor creates an invalid view.
 
 xiiStringView (char *pStart)
 Creates a string view starting at the given position, ending at the next '\0' terminator.
 
template<typename T>
constexpr xiiStringView (T pStart, typename std::enable_if< std::is_same< T, const char * >::value, xiiInt32 >::type *=0)
 Creates a string view starting at the given position, ending at the next '\0' terminator.
 
template<typename T>
constexpr XII_ALWAYS_INLINE xiiStringView (const T &&str, typename std::enable_if< std::is_same< T, const char * >::value==false &&std::is_convertible< T, const char * >::value, xiiInt32 >::type *=0)
 Creates a string view from any class / struct which is implicitly convertible to const char *.
 
constexpr xiiStringView (const char *pStart, const char *pEnd)
 Creates a string view for the range from pStart to pEnd.
 
constexpr xiiStringView (const char *pStart, xiiUInt32 uiLength)
 Creates a string view for the range from pStart to pStart + uiLength.
 
template<size_t N>
constexpr xiiStringView (const char(&str)[N])
 Construct a string view from a string literal.
 
template<size_t N>
constexpr xiiStringView (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+= (xiiUInt32 d)
 Advances the start forwards by d characters. Does not move it beyond the range's end.
 
xiiUInt32 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 (xiiStringBuilder &ref_sTempStorage) const
 Returns the data as a zero-terminated string.
 
xiiUInt32 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 (xiiStringView sOther) const
 Compares this string view with the other string view for equality.
 
bool IsEqual_NoCase (xiiStringView sOther) const
 Compares this string view with the other string view for equality.
 
bool IsEqualN (xiiStringView sOther, xiiUInt32 uiCharsToCompare) const
 Compares up to a given number of characters of this string with the other string for equality. Case insensitive.
 
bool IsEqualN_NoCase (xiiStringView sOther, xiiUInt32 uiCharsToCompare) const
 Compares up to a given number of characters of this string with the other string for equality. Case insensitive.
 
xiiInt32 Compare (xiiStringView sOther) const
 Compares this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise.
 
xiiInt32 CompareN (xiiStringView sOther, xiiUInt32 uiCharsToCompare) const
 
xiiInt32 Compare_NoCase (xiiStringView sOther) const
 Compares this string with the other one. Returns 0 for equality, -1 if this string is 'smaller', 1 otherwise. Case insensitive.
 
xiiInt32 CompareN_NoCase (xiiStringView sOther, xiiUInt32 uiCharsToCompare) const
 
bool StartsWith (xiiStringView sStartsWith) const
 Returns true, if this string starts with the given string.
 
bool StartsWith_NoCase (xiiStringView sStartsWith) const
 Returns true, if this string starts with the given string. Case insensitive.
 
bool EndsWith (xiiStringView sEndsWith) const
 Returns true, if this string ends with the given string.
 
bool EndsWith_NoCase (xiiStringView sEndsWith) const
 Returns true, if this string ends with the given string. Case insensitive.
 
const char * ComputeCharacterPosition (xiiUInt32 uiCharacterIndex) const
 Computes the pointer to the n-th character in the string. This is a linear search from the start.
 
const char * FindSubString (xiiStringView sStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindSubString_NoCase (xiiStringView sStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindLastSubString (xiiStringView sStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindLastSubString_NoCase (xiiStringView sStringToFind, const char *szStartSearchAt=nullptr) const
 
const char * FindWholeWord (const char *szSearchFor, xiiStringUtils::XII_CHARACTER_FILTER isDelimiterCB, const char *szStartSearchAt=nullptr) const
 
const char * FindWholeWord_NoCase (const char *szSearchFor, xiiStringUtils::XII_CHARACTER_FILTER isDelimiterCB, const char *szStartSearchAt=nullptr) const
 
void Shrink (xiiUInt32 uiShrinkCharsFront, xiiUInt32 uiShrinkCharsBack)
 Shrinks the view range by uiShrinkCharsFront characters at the front and by uiShrinkCharsBack characters at the back.
 
xiiStringView GetShrunk (xiiUInt32 uiShrinkCharsFront, xiiUInt32 uiShrinkCharsBack=0) const
 Returns a sub-string that is shrunk at the start and front by the given amount of characters (not bytes!).
 
xiiStringView GetSubString (xiiUInt32 uiFirstCharacter, xiiUInt32 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=" \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 (xiiStringView sWord)
 If the string starts with the given word (case insensitive), it is removed and the function returns true.
 
bool TrimWordEnd (xiiStringView 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 xiiStringView's which represent each found substring. If bReturnEmptyStrings is true, even empty strings between separators are returned. Output must be a container that stores xiiStringView'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 (xiiStringView sExtension) const
 Checks whether the given path ends with the given extension. szExtension may start with a '.', but doesn't have to.
 
xiiStringView 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.
 
xiiStringView GetFileName () const
 Returns the file name of a path, excluding the path and extension.
 
xiiStringView GetFileNameAndExtension () const
 Returns the substring that represents the file name including the file extension.
 
xiiStringView 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 xiiFileSystem for details.
 
xiiStringView GetRootedPathRootName () const
 Extracts the root name from a rooted path.
 
template<typename T>
constexpr XII_ALWAYS_INLINE xiiStringView (T pStart, typename std::enable_if< std::is_same< T, const char * >::value, xiiInt32 >::type *)
 
template<size_t N>
constexpr XII_ALWAYS_INLINE xiiStringView (const char(&str)[N])
 
template<size_t N>
constexpr XII_ALWAYS_INLINE xiiStringView (char(&str)[N])
 

Detailed Description

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

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

Member Function Documentation

◆ CompareN()

xiiInt32 xiiStringView::CompareN ( xiiStringView sOther,
xiiUInt32 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()

xiiInt32 xiiStringView::CompareN_NoCase ( xiiStringView sOther,
xiiUInt32 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 * xiiStringView::FindLastSubString ( xiiStringView 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 * xiiStringView::FindLastSubString_NoCase ( xiiStringView 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 * xiiStringView::FindSubString ( xiiStringView 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 a xiiStringView which points to the next position and call FindSubString again.

◆ FindSubString_NoCase()

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

◆ FindWholeWord()

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

◆ GetElementCount()

xiiUInt32 xiiStringView::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 * xiiStringView::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()

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

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

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

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

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

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

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

◆ GetSubString()

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

◆ HasExtension()

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

XII_ALWAYS_INLINE void xiiStringView::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 xiiStringView::Shrink ( xiiUInt32 uiShrinkCharsFront,
xiiUInt32 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: