You.i Engine
CYIString Class Reference

Detailed Description

Container class for Unicode strings. Conceptually, a CYIString object is a sequence of Unicode characters.

The native format for this string is UTF-8 encoded values, but the CYIString type can convert to and from other string formats such as UTF-16 and UTF-32. Unicode is an international standard employed by operating systems across the globe for managing writing systems used by most languages.

All constructor make a copy of the provided object or data array. For constructors that take in a data array, it is the responsability of the caller to delete the array when it is no longer needed.

The char constructors assume that the incoming data is encoded in UTF-8 already. For performance reasons, this assumption is not checked during the constructor. If invalid data (or non-UTF-8) data is provided in one of the constructors, usage of some functions may result in undefined behaviour.

Some of the functions in this class accept a parameter to enable case-insensitive searching and comparing. However, there is no Unicode Normalization performed (and thus two strings that should be equal can be reported as not equal).

For platforms that support C++/CX, the CYIStringCXUtilities class contains utilities for converting to and from WinRT string classes.

Warning
All case-insensitive functions in this class only ignore case on plain ASCII characters, even if the string contains non-ASCII characters. If case-insensitivity is required on non-ASCII characters, use the functions in CYIStringICU.
Note
When using the overloaded const char * functions, its important to note that these functions stop looking at the first null character. Consequently, these functions might behave incorrectly when they CYIString itself contains null characters (which is allowed).
See also
CYIStringView
CYIStringICU

#include <utility/YiString.h>

Classes

class  ConstIterator
 

Public Types

enum  CaseMode {
  CaseMode::CaseSensitive,
  CaseMode::CaseInsensitiveASCII
}
 
typedef std::reverse_iterator< ConstIteratorConstReverseIterator
 
typedef ConstIterator Iterator
 
typedef std::reverse_iterator< IteratorReverseIterator
 

Public Member Functions

 CYIString ()
 
 CYIString (const CYIString &s)
 
 CYIString (CYIString &&s) noexcept
 
 CYIString (CYIStringView stringView)
 
 CYIString (std::string &&string) noexcept
 
 CYIString (const std::string &s)
 
 CYIString (char32_t character)
 
 CYIString (const ConstIterator &begin, const ConstIterator &end)
 
 CYIString (const std::wstring &s)
 
 CYIString (const NSString *pString)
 
 CYIString (const CFStringRef string)
 
 CYIString (const char *pUTF8)
 
 CYIString (const char *pUTF8, size_t sizeBytes)
 
 CYIString (const char16_t *pUTF16, size_t size=NPos)
 
 CYIString (const char32_t *pUTF32, size_t size=NPos)
 
 CYIString (const wchar_t *pWideChars, size_t size=NPos)
 
 CYIString (const std::vector< char > &vector)
 
 CYIString (const std::vector< uint8_t > &vector)
 
 operator CYIStringView () const noexcept
 
CYIStringoperator= (const CYIString &s)
 
CYIStringoperator= (const char *pUTF8)
 
CYIStringoperator= (CYIString &&s) noexcept
 
CYIStringoperator= (std::string &&s) noexcept
 
bool operator< (const char *pOther) const
 
bool operator> (const char *pOther) const
 
bool operator<= (const char *pOther) const
 
bool operator>= (const char *pOther) const
 
char32_t operator[] (size_t pos) const
 
void Reserve (size_t bytes)
 
CYIStringoperator+= (CYIStringView view)
 
CYIStringoperator+= (const char *pUTF8)
 
template<class T , class = std::enable_if_t<!std::is_convertible<const T &, CYIStringView>::value >>
CYIString operator+ (const T &arg) const
 
CYIString operator+ (const char *pUTF8) const
 
bool IsEmpty () const
 
bool IsNotEmpty () const
 
size_t GetLength () const
 
size_t GetSizeInBytes () const
 
bool ContainsNonASCII () const
 
char32_t At (size_t pos) const
 
char ByteAt (size_t byteOffset) const
 
bool Contains (CYIStringView s, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
bool Contains (const char *pString, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
bool StartsWith (CYIStringView s, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
bool StartsWith (const char *pString, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
bool EndsWith (CYIStringView s, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
bool EndsWith (const char *pString, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
int32_t Compare (CYIStringView s, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
int32_t Compare (const char *pString, CaseMode caseSensitivity=CaseMode::CaseSensitive) const
 
bool Equals (CYIStringView other, CaseMode caseSensitivity=CaseMode::CaseSensitive) const noexcept
 
bool EqualsCaseInsensitiveASCII (CYIStringView other) const noexcept
 
std::vector< CYIStringSplit (CYIStringView delimiter, bool ignoreEmptySubstrings=true, size_t maximumParts=NPos) const
 
CYIString SubStr (size_t pos=0, size_t len=NPos) const
 
CYIString SubStr (const ConstIterator &begin, const ConstIterator &end) const
 
CYIString Left (size_t len) const
 
CYIString Right (size_t len) const
 
CYIString ToUpperASCII () const
 
CYIString ToLowerASCII () const
 
bool IsNumeric () const
 
size_t IndexOf (CYIStringView view, size_t pos=0) const
 
size_t IndexOf (const char *pString, size_t pos=0) const
 
size_t LastIndexOf (CYIStringView view, size_t pos=NPos) const
 
size_t LastIndexOf (const char *pString, size_t pos=NPos) const
 
ConstIterator Find (CYIStringView view, const ConstIterator &begin) const
 
ConstIterator Find (const char *pString, const ConstIterator &begin) const
 
ConstReverseIterator ReverseFind (CYIStringView view, const ConstReverseIterator &begin) const
 
ConstReverseIterator ReverseFind (const char *pString, const ConstReverseIterator &begin) const
 
CYIString Arg (CYIStringView text) const
 
const char * GetData () const
 
ConstIterator begin () const
 
ConstIterator end () const
 
ConstReverseIterator rbegin () const
 
ConstReverseIterator rend () const
 
void Clear ()
 
CYIStringAppend (CYIStringView view)
 
CYIStringAppend (const char *pUTF8, size_t sizeBytes=NPos)
 
ConstIterator Append (const ConstIterator &begin, const ConstIterator &end)
 
CYIStringPrepend (CYIStringView view)
 
CYIStringPrepend (const char *pUTF8, size_t sizeBytes=NPos)
 
ConstIterator Prepend (const ConstIterator &begin, const ConstIterator &end)
 
CYIStringInsert (CYIStringView view, size_t pos, size_t len=NPos)
 
CYIStringInsert (const char *pString, size_t pos, size_t len=NPos)
 
ConstIterator Insert (CYIStringView view, const ConstIterator &insertPosition)
 
ConstIterator Insert (const char *pString, const ConstIterator &insertPosition)
 
ConstIterator Insert (const ConstIterator &begin, const ConstIterator &end, const ConstIterator &insertPosition)
 
CYIStringErase (size_t pos=0, size_t len=NPos)
 
ConstIterator Erase (const ConstIterator &begin, const ConstIterator &end)
 
CYIStringReplace (CYIStringView view, size_t pos, size_t len)
 
CYIStringReplace (const char *pString, size_t pos, size_t len)
 
ConstIterator Replace (CYIStringView view, const ConstIterator &begin, const ConstIterator &end)
 
ConstIterator Replace (const char *pString, const ConstIterator &begin, const ConstIterator &end)
 
CYIStringReplace (CYIStringView oldSubstring, CYIStringView newSubstring, size_t maximumReplacements=NPos)
 
CYIStringReplace (const char *pOldSubstring, const char *pNewSubstring, size_t maximumReplacements=NPos)
 
void Remove (CYIStringView text)
 
void Remove (const char *pString)
 
void Swap (CYIString &s)
 
void Trim ()
 
void TrimLeft (size_t len=NPos)
 
void TrimRight (size_t len=NPos)
 
void RemovePrefix (size_t len)
 
bool RemovePrefix (CYIStringView prefix, CaseMode caseSensitivity=CaseMode::CaseSensitive)
 
void RemoveSuffix (size_t len)
 
bool RemoveSuffix (CYIStringView prefix, CaseMode caseSensitivity=CaseMode::CaseSensitive)
 
std::unique_ptr< char[]> ToUTF8 (size_t *pElementsCount=nullptr) const
 
std::unique_ptr< char16_t[]> ToUTF16 (size_t *pElementsCount=nullptr) const
 
std::unique_ptr< char32_t[]> ToUTF32 (size_t *pElementsCount=nullptr) const
 
std::unique_ptr< wchar_t[]> ToWideChars (size_t *pElementsCount=nullptr) const
 
const std::string & ToStdString () const
 
std::wstring ToStdWString () const
 
NSString * ToNSString () const
 
CFStringRef ToCFStringRef () const
 
std::string TakeStdString ()
 
template<class T >
To (bool *pError=nullptr) const
 
template<class T >
ToValue (bool *pError=nullptr) const
 
float ToFloat (bool *pError=nullptr) const
 
double ToDouble (bool *pError=nullptr) const
 
bool ToBool (bool *pError=nullptr) const
 
CYIString ToHexadecimal () const
 

Static Public Member Functions

static const CYIStringEmptyString ()
 
template<class T , class O = std::ostringstream>
static CYIString FromValue (const T &arg, bool *pError=nullptr)
 
static CYIString FromValue (bool arg, bool *pError=nullptr)
 
static CYIString FromFloat (float value, uint32_t decimalPlaces=6, bool trailingZeroes=false, bool useSignificantDigits=false)
 
static CYIString FromDouble (double value, uint32_t decimalPlaces=6, bool trailingZeroes=false, bool useSignificantDigits=false)
 
static const CYIStringFromBool (bool value)
 
template<typename Container , typename Printer = bool>
static CYIString Join (Container &&container, CYIStringView separator, bool includeEmptyElements=true, Printer &&toStringFunction=false)
 

Static Public Attributes

static constexpr size_t NPos = ~size_t(0)
 

Friends

class CYIStringView
 
std::istream & operator>> (std::istream &stream, CYIString &val)
 

Member Typedef Documentation

◆ ConstReverseIterator

typedef std::reverse_iterator<ConstIterator> CYIString::ConstReverseIterator

◆ Iterator

◆ ReverseIterator

typedef std::reverse_iterator<Iterator> CYIString::ReverseIterator

Member Enumeration Documentation

◆ CaseMode

enum CYIString::CaseMode
strong

An enum used to specify a case-sensitivity handling mode.

Note
For 'true' case-insensitive functions, see CYIStringICU.
Enumerator
CaseSensitive 

Searches and compares are performed in a case-sensitive way. This case mode is typically faster than other case modes.

CaseInsensitiveASCII 

Searches and compares are performed in a case-insensitive way. Only characters in the range [a-zA-Z] are compared in a case-insensitive manner.

Constructor & Destructor Documentation

◆ CYIString() [1/18]

CYIString::CYIString ( )

Creates an empty string.

◆ CYIString() [2/18]

CYIString::CYIString ( const CYIString s)

Constructs a string from another CYIString type s. The resulting string will be a copy of the original.

◆ CYIString() [3/18]

CYIString::CYIString ( CYIString &&  s)
noexcept

Constructs a string from another CYIString type s using move semantics.

◆ CYIString() [4/18]

CYIString::CYIString ( CYIStringView  stringView)

Constructs a string from a CYIStringView. The data referenced by the string view is copied into the new string instance.

◆ CYIString() [5/18]

CYIString::CYIString ( std::string &&  string)
noexcept

Constructs a string from another std::string type string using move semantics.

◆ CYIString() [6/18]

CYIString::CYIString ( const std::string &  s)

Constructs a string from a std::string type s. The resulting string will be a copy of the original.

Note
The data in the std::string is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ CYIString() [7/18]

CYIString::CYIString ( char32_t  character)
explicit

Constructs a string from a single Unicode character.

Note
Passing the value 0 does not create an empty string. Instead, it creates a string of length 1 containing the null character.

◆ CYIString() [8/18]

CYIString::CYIString ( const ConstIterator begin,
const ConstIterator end 
)

Constructs a string from a pair of CYIString iterators.

Warning
The two iterators must have been created from the same CYIString. Passing in two iterators created from different strings will result in undefined behaviour. Passing a begin iterator that is after the end iterator will also result in undefined behaviour.

◆ CYIString() [9/18]

CYIString::CYIString ( const std::wstring &  s)

Constructs a string from a std::wstring type s. The resulting string will be a copy of the original.

Note
The assumed encoding of the array depends on the size of wchar_t: if wchar_t is 2 bytes wide, the data is considered to be encoded in UTF-16; otherwise, it is expected to be encoded in UTF-32. This mirrors the behaviour of the ToWideChars function.

◆ CYIString() [10/18]

CYIString::CYIString ( const NSString *  pString)

Constructs a string from an NSString Objective-C object. Passing nil to this constructor will result in an empty string being created.

Note
Only available on Objective-C platforms.

◆ CYIString() [11/18]

CYIString::CYIString ( const CFStringRef  string)

Constructs a string from a CFString reference. Passing nil to this constructor will result in an empty string being created.

Note
Only available on Objective-C platforms.

◆ CYIString() [12/18]

CYIString::CYIString ( const char *  pUTF8)

Constructs a string from a UTF-8 encoded array pUTF8, which must be null terminated; providing nullptr instead results in an empty string.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ CYIString() [13/18]

CYIString::CYIString ( const char *  pUTF8,
size_t  sizeBytes 
)

Constructs a string from a UTF-8 encoded array pUTF8; providing nullptr instead results in an empty string. The sizeBytes parameter determines the number of bytes to read from the array.

Note
This constructor reads exactly sizeBytes bytes from the provided array, even if null elements are encountered. Consequently, the provided size should not include the terminating null character (if it exists).
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ CYIString() [14/18]

CYIString::CYIString ( const char16_t *  pUTF16,
size_t  size = NPos 
)

Constructs a string from a UTF-16 encoded array pUTF16; providing nullptr instead results in an empty string.

By default, this constructor expects a null-terminated array. The size parameter can be used to instead provide a number of char16_t elements to read from the array.

Note
When a size is provided in sizeBytes, this constructor reads exactly size elements from the provided array, even if null elements are encountered. Consequently, the provided size should not include the terminating null character (if it exists).

◆ CYIString() [15/18]

CYIString::CYIString ( const char32_t *  pUTF32,
size_t  size = NPos 
)

Constructs a string from a UTF-32 encoded array pUTF32; providing nullptr instead results in an empty string.

By default, this constructor expects a null-terminated array. The size parameter can be used to instead provide a number of char32_t elements to read from the array.

Note
When a size is provided in sizeBytes, this constructor reads exactly size elements from the provided array, even if null elements are encountered. Consequently, the provided size should not include the terminating null character (if it exists).

◆ CYIString() [16/18]

CYIString::CYIString ( const wchar_t *  pWideChars,
size_t  size = NPos 
)

Constructs a string from a null-terminated wide character array pWideChars; providing nullptr instead results in an empty string.

By default, this constructor expects a null-terminated array. The size parameter can be used to instead provide a number of wchar_t elements to read from the array.

Note
The assumed encoding of the array depends on the size of wchar_t: if wchar_t is 2 bytes wide, the data is considered to be encoded in UTF-16; otherwise, it is expected to be encoded in UTF-32. This mirrors the behaviour of the ToWideChars function.

◆ CYIString() [17/18]

CYIString::CYIString ( const std::vector< char > &  vector)

Constructs a string from a UTF-8 encoded vector of char's vector.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ CYIString() [18/18]

CYIString::CYIString ( const std::vector< uint8_t > &  vector)

Constructs a string from a UTF-8 encoded vector of uint8_t's vector.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

Member Function Documentation

◆ Append() [1/3]

CYIString& CYIString::Append ( CYIStringView  view)

Appends the incoming string view view to the current string.

◆ Append() [2/3]

CYIString& CYIString::Append ( const char *  pUTF8,
size_t  sizeBytes = NPos 
)

Appends the incoming string pUTF8 to the current string.

By default, this function expects a null-terminated array. The size parameter can be used to instead provide a number of bytes to read from the array. If pUTF8 is nullptr, this function does nothing.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ Append() [3/3]

ConstIterator CYIString::Append ( const ConstIterator begin,
const ConstIterator end 
)

Appends the string defined by the pair of iterators begin and end to this string. The provided iterators do not have to be from this string, but they both have to have been created from the same string.

The returned iterator points to the end of the string.

◆ Arg()

CYIString CYIString::Arg ( CYIStringView  text) const

Returns a new instance of the CYIString with the lowest-numbered 'marker' replaced with the string view text.

Markers are expected to be in the format xx, with xx being a number between 1 and 99 inclusively. Out-of-range values will result in undefined behaviour. Markers are not required to occur in order in the string. The same marker can be used multiple times within the string, which will result in all of those markers being replaced by the same argument.

Example: CYIString("%2, %1! %2!").Arg("World").Arg("Hello") would return "Hello, World! Hello!"

◆ At()

char32_t CYIString::At ( size_t  pos) const

Returns the 32-bit Unicode value at that character position specified by pos. The position must be a valid index position in the string; otherwise, a value of 0 is returned.

Note
This function runs in O(n) time. When many (or all) characters need to be accessed, it is recommended to instead use iterators.

◆ begin()

ConstIterator CYIString::begin ( ) const

Returns the iterator to the beginning of the string. This iterator iterates over Unicode characters rather than over bytes.

◆ ByteAt()

char CYIString::ByteAt ( size_t  byteOffset) const

Returns the byte value at the position byteOffset. If byteOffset is larger than the size (in bytes) of the string, 0 is returned.

Note
This function runs in O(1) time.
See also
GetSizeInBytes

◆ Clear()

void CYIString::Clear ( )

Empties the string and resets the length to 0.

◆ Compare() [1/2]

int32_t CYIString::Compare ( CYIStringView  s,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Compares this string with s. Returns a negative value if this string is less than s, zero if the two strings are equal and a positive value if this string is greater than s.

If a case-insenstive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::CompareCaseInsensitive

◆ Compare() [2/2]

int32_t CYIString::Compare ( const char *  pString,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Compares this string with pString. Returns a negative value if this string is less than pString, zero if the two strings are equal and a positive value if this character is greater than pString.

If a case-insenstive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::CompareCaseInsensitive

◆ Contains() [1/2]

bool CYIString::Contains ( CYIStringView  s,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Returns true if the string contains s as a sub-string. An empty string will be contained in any other string.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::ContainsCaseInsensitive

◆ Contains() [2/2]

bool CYIString::Contains ( const char *  pString,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Returns true if the string contains the sub-string pString. An empty string will be contained in any other string.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::ContainsCaseInsensitive

◆ ContainsNonASCII()

bool CYIString::ContainsNonASCII ( ) const

Returns true if the string contains non-ASCII characters.

Note
This function runs in O(n) time.

◆ EmptyString()

static const CYIString& CYIString::EmptyString ( )
static

Returns an instance of an empty string. Useful for functions that return references.

◆ end()

ConstIterator CYIString::end ( ) const

Returns the iterator to the end of the string. This iterator iterates over Unicode characters rather than over bytes.

◆ EndsWith() [1/2]

bool CYIString::EndsWith ( CYIStringView  s,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Returns true if the string ends with the sub-string s.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Empty strings are 'found' at the end of every string.
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::EndsWithCaseInsensitive

◆ EndsWith() [2/2]

bool CYIString::EndsWith ( const char *  pString,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Returns true if the string ends with the sub-string pString.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Empty strings are 'found' at the end of every string.
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::EndsWithCaseInsensitive

◆ Equals()

bool CYIString::Equals ( CYIStringView  other,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const
noexcept

Returns true if this string is equal to other.

If a case-insenstive compare is needed, pass CYIString::CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::EqualsCaseInsensitive

◆ EqualsCaseInsensitiveASCII()

bool CYIString::EqualsCaseInsensitiveASCII ( CYIStringView  other) const
noexcept

Returns true if this string is equal to other, ignoring case differences on ASCII characters.

Note
This is a convenience function that is equivalent to calling Equals with CYIString::CaseMode::CaseInsensitiveASCII.
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIString::Equals
CYIStringICU::EqualsCaseInsensitive

◆ Erase() [1/2]

CYIString& CYIString::Erase ( size_t  pos = 0,
size_t  len = NPos 
)

Removes a portion of the string from character position pos for len characters.

◆ Erase() [2/2]

ConstIterator CYIString::Erase ( const ConstIterator begin,
const ConstIterator end 
)

Removes a portion of the string from iterator begin to iterator end.

The returned iterator points to the character following the last erased character.

◆ Find() [1/2]

ConstIterator CYIString::Find ( CYIStringView  view,
const ConstIterator begin 
) const

Returns the iterator pointing to the next occurrence of view within this string, starting at position begin. Returns End() if view is not found.

◆ Find() [2/2]

ConstIterator CYIString::Find ( const char *  pString,
const ConstIterator begin 
) const

Returns the iterator pointing to the next occurrence of pString within this string, starting at position begin. Returns End() if sub-string pString is not found.

◆ FromBool()

static const CYIString& CYIString::FromBool ( bool  value)
static

Returns the string 'true' if value is true; returns the string 'false' otherwise.

◆ FromDouble()

static CYIString CYIString::FromDouble ( double  value,
uint32_t  decimalPlaces = 6,
bool  trailingZeroes = false,
bool  useSignificantDigits = false 
)
static

Converts the double value value to a string.

The maximum number of decimal places to display can be configured using the decimalPlaces parameter. By default, up to 6 digits are displayed. Use std::numeric_limits<double>::digits10 to display as many digits as can be represented in a floating point value.

By default, trailing zeroes (such as in 1.50000) are omitted (with the exception of the zero after the decimal point). The trailing zeroes can be displayed by setting trailingZeroes to true.

If the useSignificantDigits parameter is set to true, the 'decimal places' parameter is instead interpreted to mean the number of significant digits to be displayed.

Note
The not-a-number, positive infinity and negative infinity values are converted to 'nan', 'inf' and '-inf' respectively.

◆ FromFloat()

static CYIString CYIString::FromFloat ( float  value,
uint32_t  decimalPlaces = 6,
bool  trailingZeroes = false,
bool  useSignificantDigits = false 
)
static

Converts the float value value to a string.

The maximum number of decimal places to display can be configured using the decimalPlaces parameter. By default, up to 6 digits are displayed. Use std::numeric_limits<float>::digits10 to display as many digits as can be represented in a floating point value.

By default, trailing zeroes (such as in 1.50000) are omitted (with the exception of the zero after the decimal point). The trailing zeroes can be displayed by setting trailingZeroes to true.

If the useSignificantDigits parameter is set to true, the 'decimal places' parameter is instead interpreted to mean the number of significant digits to be displayed.

Note
The not-a-number, positive infinity and negative infinity values are converted to 'nan', 'inf' and '-inf' respectively.

◆ FromValue() [1/2]

template<class T , class O = std::ostringstream>
static CYIString CYIString::FromValue ( const T &  arg,
bool *  pError = nullptr 
)
static

Converts the templated value arg to a string. Custom types are supported so long as they have an implementation of operator<< .

If a conversion error occurs, an empty string is returned. A pointer to a boolean, pError, can optionally be provided – if a conversion error occurs, its pointed-to boolean will be set to true. If no conversion error occurs, the pointed-to boolean will be set to false.

Note
When used with non-primitive types, the sstream header must be included.

Sample usage:

CYIString convertedValue = CYIString::FromValue(42);

◆ FromValue() [2/2]

static CYIString CYIString::FromValue ( bool  arg,
bool *  pError = nullptr 
)
static

Converts the value arg to a string.

An optional pError pointer is provided for compatibility with generic CYIString::FromValue(const T&, bool*) call; if provided, a value of false will be assigned to the pointed variable since this call cannot fail.

Note
This method treats the boolean argument as an integer value of either 0 or 1, hence the result of the conversion is either "0" or "1". If you need to generate symbolic "true"/"false" values instead, use CYIString::FromBool instead
See also
CYIString::FromBool

◆ GetData()

const char* CYIString::GetData ( ) const

Returns the raw bytes that back this string. While internally the string is encoded in UTF-8, for forward compatibility this should not be relied upon.

Warning
Do not retain or delete this pointer! It is provided for compatibility with other libraries.
Calling any of the non-const functions of this class may result in the pointer returned by this function to be invalidated.
See also
ToUTF8(size_t *) const

◆ GetLength()

size_t CYIString::GetLength ( ) const

Returns the number of Unicode characters present in the string.

Note
This function runs in O(n) time the first time it is called, and O(1) time on subsequent calls. If the string is modified, the access time resets to O(n).
The IsEmpty() function is preferred to check if the string is empty, as that function always runs in O(1) time.

◆ GetSizeInBytes()

size_t CYIString::GetSizeInBytes ( ) const

Returns the size of the string in bytes. This does not include the terminating null character – that is, an empty string has a bytes count of 0.

Note
This function always runs in O(1) time.

◆ IndexOf() [1/2]

size_t CYIString::IndexOf ( CYIStringView  view,
size_t  pos = 0 
) const

Returns the character index of the sub-string view within this string; the function returns CYIString::NPos if the sub-string was not found.

If pos is provided, the search will start at the provided character index.

Note
A case-insensitive version of this function is not available because the length of the string (and therefore the indicies) may be different after case conversion.

◆ IndexOf() [2/2]

size_t CYIString::IndexOf ( const char *  pString,
size_t  pos = 0 
) const

Returns the character index of the sub-string pString within this string; the function returns CYIString::NPos if the sub-string was not found.

If pos is provided, the search will start at the provided character index.

Note
A case-insensitive version of this function is not available because the length of the string (and therefore the indicies) may be different after case conversion.

◆ Insert() [1/5]

CYIString& CYIString::Insert ( CYIStringView  view,
size_t  pos,
size_t  len = NPos 
)

Inserts the incoming string view view into the current string at character position pos.

If a value is provided for len, only len characters of view will be inserted into this string.

If pos is larger than the number of characters in this string, the provided string view is appended to this one.

◆ Insert() [2/5]

CYIString& CYIString::Insert ( const char *  pString,
size_t  pos,
size_t  len = NPos 
)

Inserts the incoming string pString into the current string at character position pos. If a value is provided for len, only len characters of pString will be inserted into this string. If pos is larger than the number of characters in this string, the provided string is appended to this one.

◆ Insert() [3/5]

ConstIterator CYIString::Insert ( CYIStringView  view,
const ConstIterator insertPosition 
)

Inserts the incoming string view view into the current string at the position represented by the iterator insertPosition. The returned iterator points to the position after the last inserted character.

◆ Insert() [4/5]

ConstIterator CYIString::Insert ( const char *  pString,
const ConstIterator insertPosition 
)

Inserts the incoming string pString into the current string at the position represented by the iterator insertPosition. The returned iterator points to the position after the last inserted character.

◆ Insert() [5/5]

ConstIterator CYIString::Insert ( const ConstIterator begin,
const ConstIterator end,
const ConstIterator insertPosition 
)

Inserts the string defined by the pair of iterators begin and end into the current string at the position represented by the iterator insertPosition. The start and end iterators may not be created from this string, and must both be created from teh same string. The returned iterator points to the position after the last inserted character.

◆ IsEmpty()

bool CYIString::IsEmpty ( ) const

Returns true if the string's length is 0, false otherwise.

Note
This function runs in O(1) time.

◆ IsNotEmpty()

bool CYIString::IsNotEmpty ( ) const

Returns true if the string's length is greater than 0, false otherwise.

Note
This function runs in O(1) time.
See also
IsEmpty()

◆ IsNumeric()

bool CYIString::IsNumeric ( ) const

Returns true if all characters in this string are ASCII digits. Returns false if this string is empty.

Note
Negative and floating-point values are considered non-numeric and will result in false being returned.
This function runs in O(n) time.

◆ Join()

template<typename Container , typename Printer = bool>
static CYIString CYIString::Join ( Container &&  container,
CYIStringView  separator,
bool  includeEmptyElements = true,
Printer &&  toStringFunction = false 
)
static

Joins all elements of container, separating them by separator.

By default, empty container values are included in the output. Pass false to includeEmptyElements to skip empty values.

By default, elements are converted to CYIString using CYIString::FromValue(). For unsupported types (or to further process the values), a callable object can be passed in to toStringFunction. The callable object must take the value as parameter, and return a CYIString (or an object convertible to CYIStringView).

Note
When used with non-primitive types and the default object printer, the sstream header must be included.

Sample usage:

CYIString result = CYIString::Join(container, ", ", false, [](auto &&value) {
return value.ToUpperASCII();
});
See also
Split

◆ LastIndexOf() [1/2]

size_t CYIString::LastIndexOf ( CYIStringView  view,
size_t  pos = NPos 
) const

Returns the character index of the sub-string view within this string, starting at the end and searching in reverse; the function returns CYIString::NPos if the sub-string was not found.

If pos is provided, the search will start at the provided character index instead of at the end of the string. In that case, pos would be the position of the last character that would be considered for the beginning of the string view.

Note
A case-insensitive version of this function is not available because the length of the string (and therefore the indicies) may be different after case conversion.

◆ LastIndexOf() [2/2]

size_t CYIString::LastIndexOf ( const char *  pString,
size_t  pos = NPos 
) const

Returns the character index of the sub-string pString within this string, starting at the end and searching in reverse; the function returns CYIString::NPos if the sub-string was not found.

If pos is provided, the search will start at the provided character index instead of at the end of the string. In that case, pos would be the position of the last character that would be considered for the beginning of the string pString.

Note
A case-insensitive version of this function is not available because the length of the string (and therefore the indicies) may be different after case conversion.

◆ Left()

CYIString CYIString::Left ( size_t  len) const

Returns a string containg the first len characters of this string. If len is larger than the length of this string, the full string is returned.

◆ operator CYIStringView()

CYIString::operator CYIStringView ( ) const
noexcept

Overloaded operator to convert to a CYIStringView. The returned string view is valid only as long as this CYIString remains valid and unmodified.

◆ operator+() [1/2]

template<class T , class = std::enable_if_t<!std::is_convertible<const T &, CYIStringView>::value >>
CYIString CYIString::operator+ ( const T &  arg) const

Concatenates a type to the string. This operator makes use of FromValue() to convert arg to a string, and is equivalent to calling this->Append(CYIString::FromValue(arg));

Note
When used with non-primitive types, the sstream header must be included.

◆ operator+() [2/2]

CYIString CYIString::operator+ ( const char *  pUTF8) const

Concatenates the null-terminated string pUTF8 to the string.

◆ operator+=() [1/2]

CYIString& CYIString::operator+= ( CYIStringView  view)

Appends the string view view to the current string.

◆ operator+=() [2/2]

CYIString& CYIString::operator+= ( const char *  pUTF8)

Appends the null-terminatd string pUTF8 to the current string.

Note
The data pointed to by pUTF8 is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ operator<()

bool CYIString::operator< ( const char *  pOther) const

Returns true if this string is 'less' than the provided string. This function performs a lexicographical comparison. An empty string is considered to be 'smaller' than any other non-empty string.

◆ operator<=()

bool CYIString::operator<= ( const char *  pOther) const

Returns true if this string is 'less' than or equal to the provided string. This function performs a lexicographical comparison. An empty string is considered to be 'smaller' than any other non-empty string.

◆ operator=() [1/4]

CYIString& CYIString::operator= ( const CYIString s)

Assigns a copy of s to this string.

◆ operator=() [2/4]

CYIString& CYIString::operator= ( const char *  pUTF8)

Assigns a copy of the UTF-8 encoded array to this string; the array must be null terminated. Providing a nullptr value results in an empty string object.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ operator=() [3/4]

CYIString& CYIString::operator= ( CYIString &&  s)
noexcept

Moves the string data from s into this string. The string s is left empty.

◆ operator=() [4/4]

CYIString& CYIString::operator= ( std::string &&  s)
noexcept

Moves the string data from s into this string. The string s is left empty.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ operator>()

bool CYIString::operator> ( const char *  pOther) const

Returns true if this string is 'greater' than the provided string. This function performs a lexicographical comparison. An empty string is considered to be 'smaller' than any other non-empty string.

◆ operator>=()

bool CYIString::operator>= ( const char *  pOther) const

Returns true if this string is 'greater' than or equal to the provided string. This function performs a lexicographical comparison. An empty string is considered to be 'smaller' than any other non-empty string.

◆ operator[]()

char32_t CYIString::operator[] ( size_t  pos) const

Returns the 32-bit Unicode value at that character position specified by pos. Cannot be modified. The position must be a valid index position in the string; otherwise, a value of 0 is returned.

Note
This function runs in O(n) time. When many (or all) characters need to be accessed, it is recommended to instead use iterators.

◆ Prepend() [1/3]

CYIString& CYIString::Prepend ( CYIStringView  view)

Prepends the incoming string view view to the current string.

◆ Prepend() [2/3]

CYIString& CYIString::Prepend ( const char *  pUTF8,
size_t  sizeBytes = NPos 
)

Prepends the incoming string pUTF8 to the current string.

By default, this function expects a null-terminated array. The size parameter can be used to instead provide a number of bytes to read from the array. If pUTF8 is nullptr, this function does nothing.

Note
The data is assumed to be encoded with UTF-8. If the data is not encoded in UTF-8, the use of some of the CYIString functions will result in undefined behaviour.

◆ Prepend() [3/3]

ConstIterator CYIString::Prepend ( const ConstIterator begin,
const ConstIterator end 
)

Prepends the string defined by the pair of iterators begin and end to this string. The provided iterators do not have to be from this string, but they both have to have been created from the same string.

The returned iterator points to the character following the last prepended character.

◆ rbegin()

ConstReverseIterator CYIString::rbegin ( ) const

Returns the reverse iterator to the end of the string. This iterator iterates over Unicode characters rather than over bytes.

◆ Remove() [1/2]

void CYIString::Remove ( CYIStringView  text)

Remove all occurences of text from the current string.

◆ Remove() [2/2]

void CYIString::Remove ( const char *  pString)

Remove all occurences of pString from the current string.

◆ RemovePrefix() [1/2]

void CYIString::RemovePrefix ( size_t  len)

Removes the first len characters from this string. If there are fewer than len characters in the string, the string becomes empty.

◆ RemovePrefix() [2/2]

bool CYIString::RemovePrefix ( CYIStringView  prefix,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
)

Removes prefix from the beginning of this string if this string begins with prefix. Otherwise, this function does nothing. Returns true if prefix was found.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.

◆ RemoveSuffix() [1/2]

void CYIString::RemoveSuffix ( size_t  len)

Removes the last len characters from this string. If there are fewer than len characters in the string, the string becomes empty.

◆ RemoveSuffix() [2/2]

bool CYIString::RemoveSuffix ( CYIStringView  prefix,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
)

Removes suffix from the end of this string if this string ends with suffix. Otherwise, this function does nothing. Returns true if suffix was found.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Comparison of non-ASCII characters is always done in a case-sensitive manner.

◆ rend()

ConstReverseIterator CYIString::rend ( ) const

Returns the reverse iterator to the beginning of the string. This iterator iterates over Unicode characters rather than over bytes.

◆ Replace() [1/6]

CYIString& CYIString::Replace ( CYIStringView  view,
size_t  pos,
size_t  len 
)

Replaces a portion of the string from character position pos for len characters with the view string view.

If pos is larger than the length of this string, the provided string view is appended to this one. If len is longer than this string, the whole string is replaced by view.

◆ Replace() [2/6]

CYIString& CYIString::Replace ( const char *  pString,
size_t  pos,
size_t  len 
)

Replaces a portion of the string from character position pos for len characters with the pString string.

If pos is larger than the length of this string, the provided string is appended to this one. If len is longer than this string, the whole string is replaced by pString.

◆ Replace() [3/6]

ConstIterator CYIString::Replace ( CYIStringView  view,
const ConstIterator begin,
const ConstIterator end 
)

Replaces a portion of the string from iterator begin to iterator end with the string view view.

The returned iterator points to the character after the last replacement character.

◆ Replace() [4/6]

ConstIterator CYIString::Replace ( const char *  pString,
const ConstIterator begin,
const ConstIterator end 
)

Replaces a portion of the string from iterator begin to iterator end with the string pString.

The returned iterator points to the character after the last replacement character.

◆ Replace() [5/6]

CYIString& CYIString::Replace ( CYIStringView  oldSubstring,
CYIStringView  newSubstring,
size_t  maximumReplacements = NPos 
)

Replaces all occurences of the sub-string oldSubstring within this string with the sub-string newSubstring.

If value is specified for maximumReplacements, only up to maximumReplacements replacements will be performed.

Note
Passing an empty oldSubstring will result in no changes to this string.

◆ Replace() [6/6]

CYIString& CYIString::Replace ( const char *  pOldSubstring,
const char *  pNewSubstring,
size_t  maximumReplacements = NPos 
)

Replaces all occurences of the sub-string oldSubstring within this string with the sub-string newSubstring.

If value is specified for maximumReplacements, only up to maximumReplacements replacements will be performed.

Note
Passing an empty oldSubstring will result in no changes to this string.

◆ Reserve()

void CYIString::Reserve ( size_t  bytes)

Pre-allocates enough storage to store bytes bytes of data.

◆ ReverseFind() [1/2]

ConstReverseIterator CYIString::ReverseFind ( CYIStringView  view,
const ConstReverseIterator begin 
) const

Returns the iterator pointing to the 'next' occurrence of view within this string, starting at position begin. Since this function works on reverse iterators, the 'next' occurrence is really the previous occurrence within the string. Returns REnd() if view is not found.

◆ ReverseFind() [2/2]

ConstReverseIterator CYIString::ReverseFind ( const char *  pString,
const ConstReverseIterator begin 
) const

Returns the iterator pointing to the 'next' occurrence of pString within this string, starting at position begin. Since this function works on reverse iterators, the 'next' occurrence is really the previous occurrence within the string. Returns REnd() if pString is not found.

◆ Right()

CYIString CYIString::Right ( size_t  len) const

Returns a string containg the last len characters of this string. If len is larger than the length of this string, the full string is returned.

◆ Split()

std::vector<CYIString> CYIString::Split ( CYIStringView  delimiter,
bool  ignoreEmptySubstrings = true,
size_t  maximumParts = NPos 
) const

Splits the current string into a vector of strings whenever the delimeter occurs in the string.

If ignoreEmptySubstrings is true, 'empty' substrings are not included in the returned vector.

The maximumParts parameter can be used to specify the maximum number of elements to return in the vector. When more than ( maximumParts - 1 ) parts are found during splitting, the remaining parts will be left as is and appended to the vector. For example, calling CYIString("foo;bar;baz").Split(";", true, 2) would result in a vector containing 'foo' and 'bar;baz' being returned. Providing a value of 0 to maximumParts will result in an empty vector being returned, and providing a value of 1 will result in the original string being returned as the sole element in the vector. When ignoreEmptySubstrings is true, 'empty' substrings do not count towards the parts count. A value of CYIString::NPos indicates that there is no parts limit.

See also
Join

◆ StartsWith() [1/2]

bool CYIString::StartsWith ( CYIStringView  s,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Returns true if the string starts with the sub-string s.

If a case-insensitive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Empty strings are 'found' at the beginning of every string.
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::StartsWithCaseInsensitive

◆ StartsWith() [2/2]

bool CYIString::StartsWith ( const char *  pString,
CaseMode  caseSensitivity = CaseMode::CaseSensitive 
) const

Returns true if the string starts with the sub-string pString.

If a case-insenstive compare is needed, pass CaseMode::CaseInsensitiveASCII to the caseSensitivity parameter.

Note
Empty strings are 'found' at the beginning of every string.
Comparison of non-ASCII characters is always done in a case-sensitive manner.
See also
CYIStringICU::StartsWithCaseInsensitive

◆ SubStr() [1/2]

CYIString CYIString::SubStr ( size_t  pos = 0,
size_t  len = NPos 
) const

Returns the sub-string of the current string from character position pos for len characters. A len value of CYIString::NPos indicates that the sub-string from pos to the end of the string should be returned. Returns an empty string in the case of invalid pos or len values.

◆ SubStr() [2/2]

CYIString CYIString::SubStr ( const ConstIterator begin,
const ConstIterator end 
) const

Returns the sub-string of the current string from iterator begin to iterator end.

◆ Swap()

void CYIString::Swap ( CYIString s)

Swaps the contents of the string with the contents of s.

◆ TakeStdString()

std::string CYIString::TakeStdString ( )

Moves and returns the underlying std::string of this CYIString instance. After calling this function, the CYIString instance is left in an undetermined but valid state (similar to std::move'ing a CYIString instance). This function is provided for compatibility with 3rd party libraries.

◆ To()

template<class T >
T CYIString::To ( bool *  pError = nullptr) const

Converts this string to the specified template type T. Custom types are supported so long as they have an implementation of operator>> .

If a conversion error occurs, an object created with the default constructor is returned. A pointer to a boolean, pError, can optionally be provided – if a conversion error occurs, its pointed-to boolean will be set to true. If no conversion error occurs, the pointed-to boolean will be set to false.

Note
When used with non-primitive types, the sstream header must be included.

Sample usage:

int32_t convertedValue = myString.To<int32_t>();

◆ ToBool()

bool CYIString::ToBool ( bool *  pError = nullptr) const

Interprets the provided string as a boolean. The following string values will result in a value of true being returned:

  • true
  • yes
  • 1
  • on
  • enabled
  • enable
  • active

The following string values will result in a value of false being returned:

  • false
  • no
  • 0
  • off
  • disabled
  • disable
  • inactive

All string values are case-insensitive. Leading and trailing spaces are ignored.

Any other string value will be considered a conversion error and will result in a value of false being returned. A pointer to a boolean, pError, can optionally be provided – if a conversion error occurs, its pointed-to boolean will be set to true. If no conversion error occurs, the pointed-to boolean will be set to false.

Note
Empty strings will result in a value of false being returned, and is considered a conversion error.
Warning
The accepted values are not localized.

◆ ToCFStringRef()

CFStringRef CYIString::ToCFStringRef ( ) const

Returns the CFStringRef representation of this string. The caller is responsible for deleting this resource (using CFRelease).

Note
Only available on Objective-C platforms.

◆ ToDouble()

double CYIString::ToDouble ( bool *  pError = nullptr) const

Converts this string to a double-precision floating point value.

If a conversion error occurs, 0.0 is returned. A pointer to a boolean, pError, can optionally be provided – if a conversion error occurs, its pointed-to boolean will be set to true. If no conversion error occurs, the pointed-to boolean will be set to false.

◆ ToFloat()

float CYIString::ToFloat ( bool *  pError = nullptr) const

Converts this string to a single-precision floating point value.

If a conversion error occurs, 0.0f is returned. A pointer to a boolean, pError, can optionally be provided – if a conversion error occurs, its pointed-to boolean will be set to true. If no conversion error occurs, the pointed-to boolean will be set to false.

◆ ToHexadecimal()

CYIString CYIString::ToHexadecimal ( ) const

Returns the hexadecimal representation of the raw bytes that back this string. The returned characters are always in lowercase. Calling this function on an empty string returns an empty string.

For example, calling this function on the string "K" would return "4b", and calling this function on the string "You.i" would return "596f752e69".

◆ ToLowerASCII()

CYIString CYIString::ToLowerASCII ( ) const

Returns a lowercase version of this string. This string is not modified.

Note
Only the ASCII characters within the string are converted (e.g the range [A-Z]). Non-ASCII characters are left as-is.
See also
CYIStringICU::ToLower

◆ ToNSString()

NSString* CYIString::ToNSString ( ) const

Returns the NSString representation of this string.

Note
Only available on Objective-C platforms.

◆ ToStdString()

const std::string& CYIString::ToStdString ( ) const

Returns the STL string representation of this string.

◆ ToStdWString()

std::wstring CYIString::ToStdWString ( ) const

Returns the STL wstring representation of this string.

Note
The encoding of the wstring depends on the size of wchar_t: if wchar_t is 2 bytes wide, the data is encoded in UTF-16; otherwise, it is encoded in UTF-32.

◆ ToUpperASCII()

CYIString CYIString::ToUpperASCII ( ) const

Returns an uppercase version of this string. This string is not modified.

Note
Only the ASCII characters within the string are converted (e.g the range [a-z]). Non-ASCII characters are left as-is.
See also
CYIStringICU::ToUpper

◆ ToUTF16()

std::unique_ptr<char16_t[]> CYIString::ToUTF16 ( size_t pElementsCount = nullptr) const

Returns a new instance of the null-terminated UTF-16 representation of this string.

If needed, the resulting number of char16_t elements in the returned array (excluding the null terminator) can be obtained by passing in a pointer to an size_t in pElementsCount.

◆ ToUTF32()

std::unique_ptr<char32_t[]> CYIString::ToUTF32 ( size_t pElementsCount = nullptr) const

Returns a new instance of the null-terminated UTF-32 representation of this string.

If needed, the resulting number of char32_t elements in the returned array (excluding the null terminator) can be obtained by passing in a pointer to an size_t in pElementsCount.

◆ ToUTF8()

std::unique_ptr<char[]> CYIString::ToUTF8 ( size_t pElementsCount = nullptr) const

Returns a new instance of the null-terminated UTF-8 representation of this string.

If needed, the resulting number of char elements in the returned array (excluding the null terminator) can be obtained by passing in a pointer to an size_t in pElementsCount.

Note
The GetData() function can be used when a copy isn't required.
See also
GetData()

◆ ToValue()

template<class T >
T CYIString::ToValue ( bool *  pError = nullptr) const

Converts this string to the specified template type T. Custom types are supported so long as they have an implementation of operator>> .

If a conversion error occurs, an object created with the default constructor is returned. A pointer to a boolean, pError, can optionally be provided – if a conversion error occurs, its pointed-to boolean will be set to true. If no conversion error occurs, the pointed-to boolean will be set to false.

Note
When used with non-primitive types, the sstream header must be included.

Sample usage:

int32_t convertedValue = myString.To<int32_t>();
See also
To(bool *) const

◆ ToWideChars()

std::unique_ptr<wchar_t[]> CYIString::ToWideChars ( size_t pElementsCount = nullptr) const

Returns a new instance of the null-terminated wchar_t respresentation for this string.

If needed, the resulting number of wchar_t elements in the returned array (excluding the null terminator) can be obtained by passing in a pointer to an size_t pElementsCount.

Note
The encoding of the array depends on the size of wchar_t: if wchar_t is 2 bytes wide, the data is encoded in UTF-16; otherwise, it is encoded in UTF-32.

◆ Trim()

void CYIString::Trim ( )

Trims whitespace at the beginning and at the end of the string.

◆ TrimLeft()

void CYIString::TrimLeft ( size_t  len = NPos)

Trims whitespace at the beginning of the string. The amount of removed whitespace can be limited using the len parameter. By default, all whitespace characters at the beginning of the string are removed.

◆ TrimRight()

void CYIString::TrimRight ( size_t  len = NPos)

Trims whitespace at the end of the string. The amount of removed whitespace can be limited using the len parameter. By default, all whitespace characters at the end of the string are removed.

Friends And Related Function Documentation

◆ CYIStringView

friend class CYIStringView
friend

◆ operator>>

std::istream& operator>> ( std::istream &  stream,
CYIString val 
)
friend

Reads a single element from the stream stream and assigns it to the string val. By default, elements are delimited by whitespace characters, through this can be changed within the stream. The old value of val is discarded, even if an error occurred reading from the stream.

Member Data Documentation

◆ NPos

constexpr size_t CYIString::NPos = ~size_t(0)
static

A constant whose meaning is context-dependent but usually means 'not found' or 'no limit'.


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