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< ConstIterator >	ConstReverseIterator

typedef ConstIterator	Iterator

typedef std::reverse_iterator< Iterator >	ReverseIterator

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

CYIString &	operator= (const CYIString &s)

CYIString &	operator= (const char *pUTF8)

CYIString &	operator= (CYIString &&s) noexcept

CYIString &	operator= (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)

CYIString &	operator+= (CYIStringView view)

CYIString &	operator+= (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< CYIString >	Split (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 ()

CYIString &	Append (CYIStringView view)

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

ConstIterator	Append (const ConstIterator &begin, const ConstIterator &end)

CYIString &	Prepend (CYIStringView view)

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

ConstIterator	Prepend (const ConstIterator &begin, const ConstIterator &end)

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

CYIString &	Insert (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)

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

ConstIterator	Erase (const ConstIterator &begin, const ConstIterator &end)

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

CYIString &	Replace (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)

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

CYIString &	Replace (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 >
T	To (bool *pError=nullptr) const

template<class T >
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 CYIString &	EmptyString ()

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 CYIString &	FromBool (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

typedef ConstIterator CYIString::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, [](const CYIString &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:

utility/YiString.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Member Typedef Documentation

◆ ConstReverseIterator

◆ Iterator

◆ ReverseIterator

Member Enumeration Documentation

◆ CaseMode

Constructor & Destructor Documentation

◆ CYIString() [1/18]

◆ CYIString() [2/18]

◆ CYIString() [3/18]

◆ CYIString() [4/18]

◆ CYIString() [5/18]

◆ CYIString() [6/18]

◆ CYIString() [7/18]

◆ CYIString() [8/18]

◆ CYIString() [9/18]

◆ CYIString() [10/18]

◆ CYIString() [11/18]

◆ CYIString() [12/18]

◆ CYIString() [13/18]

◆ CYIString() [14/18]

◆ CYIString() [15/18]

◆ CYIString() [16/18]

◆ CYIString() [17/18]

◆ CYIString() [18/18]

Member Function Documentation

◆ Append() [1/3]

◆ Append() [2/3]

◆ Append() [3/3]

◆ Arg()

◆ At()

◆ begin()

◆ ByteAt()

◆ Clear()

◆ Compare() [1/2]

◆ Compare() [2/2]

◆ Contains() [1/2]

◆ Contains() [2/2]

◆ ContainsNonASCII()

◆ EmptyString()

◆ end()

◆ EndsWith() [1/2]

◆ EndsWith() [2/2]

◆ Equals()

◆ EqualsCaseInsensitiveASCII()

◆ Erase() [1/2]

◆ Erase() [2/2]

◆ Find() [1/2]

◆ Find() [2/2]

◆ FromBool()

◆ FromDouble()

◆ FromFloat()

◆ FromValue() [1/2]

◆ FromValue() [2/2]

◆ GetData()

◆ GetLength()

◆ GetSizeInBytes()

◆ IndexOf() [1/2]

◆ IndexOf() [2/2]

◆ Insert() [1/5]

◆ Insert() [2/5]

◆ Insert() [3/5]

◆ Insert() [4/5]

◆ Insert() [5/5]

◆ IsEmpty()

◆ IsNotEmpty()

◆ IsNumeric()

◆ Join()

◆ LastIndexOf() [1/2]

◆ LastIndexOf() [2/2]

◆ Left()

◆ operator CYIStringView()

◆ operator+() [1/2]