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.

#include <utility/YiString.h>

Classes
class	ConstIterator

Public Types
enum	CASE_MODE { CASE_SENSITIVE, CASE_INSENSITIVE }

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)

	CYIString (std::string &&string)

	CYIString (const std::string &s)

	CYIString (char32_t character)

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

	CYIString (const std::wstring &s)

	CYIString (const U_NAMESPACE_QUALIFIER UnicodeString &s, uint32_t uSizeHintBytes=0)

	CYIString (const NSString *string)

	CYIString (const CFStringRef string)

	CYIString (const char *pUTF8)

	CYIString (const char *pUTF8, uint32_t uSizeBytes)

	CYIString (const char16_t *pUTF16, uint32_t uSize=std::numeric_limits< uint32_t >::max())

	CYIString (const char32_t *pUTF32, uint32_t uSize=std::numeric_limits< uint32_t >::max())

	CYIString (const wchar_t *pWideChars, uint32_t uSize=std::numeric_limits< uint32_t >::max())

	operator const char * () const

CYIString &	operator= (const CYIString &s)

CYIString &	operator= (const char *pUTF8)

CYIString &	operator= (CYIString &&s)

bool	operator== (const CYIString &s) const

bool	operator== (const char *pUTF8) const

bool	operator!= (const CYIString &s) const

bool	operator!= (const char *pUTF8) const

bool	operator< (const CYIString &s1) const

bool	operator> (const CYIString &s1) const

bool	operator<= (const CYIString &s1) const

bool	operator>= (const CYIString &s1) const

char32_t	operator[] (int32_t nPos) const

CYIString &	operator+= (const CYIString &s)

CYIString &	operator+= (const char *pUTF8)

template<class T >
CYIString	operator+ (T arg) const

bool	IsEmpty () const

bool	IsNotEmpty () const

uint32_t	GetLength () const

uint32_t	GetSizeInBytes () const

bool	ContainsNonASCII () const

char32_t	At (uint32_t uPos) const

char	ByteAt (uint32_t uByteOffset) const

bool	Contains (const CYIString &s, CASE_MODE eCaseSensitivity=CASE_SENSITIVE) const

bool	StartsWith (const CYIString &s, CASE_MODE eCaseSensitivity=CASE_SENSITIVE) const

bool	EndsWith (const CYIString &s, CASE_MODE eCaseSensitivity=CASE_SENSITIVE) const

int32_t	Compare (const CYIString &s, CASE_MODE eCaseSensitivity=CASE_SENSITIVE) const

std::vector< CYIString >	Split (const CYIString &delimiter, bool bIgnoreEmptySubstrings=true, uint32_t uMaximumParts=std::numeric_limits< uint32_t >::max()) const

CYIString	SubStr (uint32_t uPos=0, uint32_t uLen=std::numeric_limits< uint32_t >::max()) const

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

CYIString	Left (uint32_t uLen) const

CYIString	Right (uint32_t uLen) const

CYIString	ToUpper () const

CYIString	ToLower () const

CYIString	ToNormalizedText (bool *pbError=nullptr) const

bool	IsNumeric () const

int32_t	IndexOf (const CYIString &s, uint32_t uPos=0) const

int32_t	LastIndexOf (const CYIString &s, uint32_t uPos=std::numeric_limits< uint32_t >::max()) const

ConstIterator	Find (const CYIString &s, const ConstIterator &begin) const

ConstReverseIterator	ReverseFind (const CYIString &s, const ConstReverseIterator &begin) const

CYIString	Arg (const CYIString &rText) const

const char *	GetData () const

ConstIterator	begin () const

ConstIterator	end () const

ConstReverseIterator	rbegin () const

ConstReverseIterator	rend () const

void	Clear ()

CYIString &	Append (const CYIString &s)

CYIString &	Append (const char *pUTF8, uint32_t uSizeBytes=std::numeric_limits< uint32_t >::max())

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

CYIString &	Prepend (const CYIString &s)

CYIString &	Prepend (const char *pUTF8, uint32_t uSizeBytes=std::numeric_limits< uint32_t >::max())

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

CYIString &	Insert (const CYIString &s, uint32_t uPos, uint32_t uLen=std::numeric_limits< uint32_t >::max())

ConstIterator	Insert (const CYIString &s, const ConstIterator &insertPosition)

ConstIterator	Insert (const ConstIterator &begin, const ConstIterator &end, const ConstIterator &insertPosition)

CYIString &	Erase (uint32_t uPos=0, uint32_t uLen=std::numeric_limits< uint32_t >::max())

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

CYIString &	Replace (const CYIString &s, uint32_t uPos, uint32_t uLen)

ConstIterator	Replace (const CYIString &s, const ConstIterator &begin, const ConstIterator &end)

CYIString &	Replace (const CYIString &oldSubstring, const CYIString &newSubstring, uint32_t uMaximumReplacements=std::numeric_limits< uint32_t >::max())

void	Remove (const CYIString &text)

void	Swap (CYIString &s)

void	Trim ()

void	TrimLeft (uint32_t uLen=std::numeric_limits< uint32_t >::max())

void	TrimRight (uint32_t uLen=std::numeric_limits< uint32_t >::max())

const char *	AsUTF8 (uint32_t *pElementsCount=nullptr) const

std::unique_ptr< char[]>	ToUTF8 (uint32_t *pElementsCount=nullptr) const

std::unique_ptr< char16_t[]>	ToUTF16 (uint32_t *pElementsCount=nullptr) const

std::unique_ptr< char32_t[]>	ToUTF32 (uint32_t *pElementsCount=nullptr) const

std::unique_ptr< wchar_t[]>	ToWideChars (uint32_t *pElementsCount=nullptr) const

const std::string &	ToStdString () const

std::wstring	ToStdWString () const

U_NAMESPACE_QUALIFIER UnicodeString	ToUnicodeString () const

NSString *	ToNSString () const

CFStringRef	ToCFStringRef () const

template<class T >
T	To (bool *pbError=nullptr) const

template<class T >
T	ToValue (bool *pbError=nullptr) const

float	ToFloat (bool *pbError=nullptr) const

double	ToDouble (bool *pbError=nullptr) const

bool	ToBool (bool *pbError=nullptr) const

Static Public Member Functions
static const CYIString &	EmptyString ()

template<class T >
static CYIString	FromValue (const T &arg, bool *pbError=nullptr)

static CYIString	FromFloat (float fValue, uint32_t uDecimalPlaces=6, bool bTrailingZeroes=false, bool bUseSignificantDigits=false)

static CYIString	FromDouble (double fValue, uint32_t uDecimalPlaces=6, bool bTrailingZeroes=false, bool bUseSignificantDigits=false)

static const CYIString &	FromBool (bool bValue)

Static Public Attributes
static const CYIString	EMPTY_STRING

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

Member Typedef Documentation

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

typedef ConstIterator CYIString::Iterator

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

Member Enumeration Documentation

enum CYIString::CASE_MODE

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

Enumerator
CASE_SENSITIVE	Searches and compares are performed in a case-sensitive way. This case mode is typically faster than other case mode.
CASE_INSENSITIVE	Searches and compares are performed in a case-insensitive way.

Constructor & Destructor Documentation

CYIString::CYIString ( )

Creates an empty string.

CYIString::CYIString ( const CYIString & s )

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

CYIString::CYIString ( CYIString && s )

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

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

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

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::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::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::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::CYIString	(	const U_NAMESPACE_QUALIFIER UnicodeString &	s,
		uint32_t	uSizeHintBytes = `0`
	)

Constructs a string from an ICU UnicodeString.

The uSizeHintBytes parameter can be used to provide a guess as to how big the resulting string will be, in bytes. This parameter is used to avoid multiple reallocations when creating a string from a long UnicodeString object.

CYIString::CYIString ( const NSString * string )

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::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::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::CYIString	(	const char *	pUTF8,
		uint32_t	uSizeBytes
	)

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

Note: This constructor reads exactly uSizeBytes 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::CYIString	(	const char16_t *	pUTF16,
		uint32_t	uSize = `std::numeric_limits< uint32_t >::max()`
	)

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 uSize 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 uSizeBytes, this constructor reads exactly uSize 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::CYIString	(	const char32_t *	pUTF32,
		uint32_t	uSize = `std::numeric_limits< uint32_t >::max()`
	)

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 uSize 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 uSizeBytes, this constructor reads exactly uSize 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::CYIString	(	const wchar_t *	pWideChars,
		uint32_t	uSize = `std::numeric_limits< uint32_t >::max()`
	)

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

Member Function Documentation

CYIString& CYIString::Append ( const CYIString & s )

Appends the incoming string s to the current string.

CYIString& CYIString::Append	(	const char *	pUTF8,
		uint32_t	uSizeBytes = `std::numeric_limits< uint32_t >::max()`
	)

Appends the incoming string pUTF8 to the current string.

By default, this function expects a null-terminated array. The uSize 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.

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.

CYIString CYIString::Arg ( const CYIString & rText ) const

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

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

const char* CYIString::AsUTF8 ( uint32_t * pElementsCount = nullptr ) const

Deprecated:: This function has been deprecated and may be removed in a future release. GetData() and GetSizeInBytes() should be used instead.

Returns the null-terminated UTF-8 representation of this string. Since this string internally stores its data as UTF-8, this function simply returns a reference to that data.

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 uint32_t in pElementsCount.

Warning: The ownership of the array is retained by this string – do not delete it!

See also: GetData()

char32_t CYIString::At ( uint32_t uPos ) const

Returns the 32-bit Unicode value at that character position specified by uPos. 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.

ConstIterator CYIString::begin ( ) const

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

char CYIString::ByteAt ( uint32_t uByteOffset ) const

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

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

See also: BytesCount

void CYIString::Clear ( )

Empties the string and resets the length to 0.

int32_t CYIString::Compare	(	const CYIString &	s,
		CASE_MODE	eCaseSensitivity = `CASE_SENSITIVE`
	)		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 CASE_INSENSITIVE to the eCaseSensitivity parameter.

bool CYIString::Contains	(	const CYIString &	s,
		CASE_MODE	eCaseSensitivity = `CASE_SENSITIVE`
	)		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-insenstive compare is needed, pass CASE_INSENSITIVE to the eCaseSensitivity parameter.

bool CYIString::ContainsNonASCII ( ) const

Returns true if the string contains non-ASCII characters.

Note: This function runs in O(n) time.

static const CYIString& CYIString::EmptyString ( )

static

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

ConstIterator CYIString::end ( ) const

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

bool CYIString::EndsWith	(	const CYIString &	s,
		CASE_MODE	eCaseSensitivity = `CASE_SENSITIVE`
	)		const

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

If a case-insenstive compare is needed, pass CASE_INSENSITIVE to the eCaseSensitivity parameter.

Note: Empty strings are 'found' at the end of every string.

CYIString& CYIString::Erase	(	uint32_t	uPos = `0`,
		uint32_t	uLen = `std::numeric_limits< uint32_t >::max()`
	)

Removes a portion of the string from character position uPos for uLen characters.

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.

ConstIterator CYIString::Find	(	const CYIString &	s,
		const ConstIterator &	begin
	)		const

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

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

static

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

static CYIString CYIString::FromDouble	(	double	fValue,
		uint32_t	uDecimalPlaces = `6`,
		bool	bTrailingZeroes = `false`,
		bool	bUseSignificantDigits = `false`
	)

static

Converts the double value fValue to a string.

The maximum number of decimal places to display can be configured using the uDecimalPlaces 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 bTrailingZeroes to true.

If the bUseSignificantDigits 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.

static CYIString CYIString::FromFloat	(	float	fValue,
		uint32_t	uDecimalPlaces = `6`,
		bool	bTrailingZeroes = `false`,
		bool	bUseSignificantDigits = `false`
	)

static

Converts the float value fValue to a string.

The maximum number of decimal places to display can be configured using the uDecimalPlaces 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 bTrailingZeroes to true.

If the bUseSignificantDigits 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.

template<class T >

static CYIString CYIString::FromValue	(	const T &	arg,
		bool *	pbError = `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, pbError, 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.

Sample usage:

CYIString convertedValue = CYIString::FromValue(42);

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: AsUTF8(YI_UINT*)

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

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

int32_t CYIString::IndexOf	(	const CYIString &	s,
		uint32_t	uPos = `0`
	)		const

Returns the character index of the sub-string s within this string; the function returns -1 if the sub-string was not found.

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

CYIString& CYIString::Insert	(	const CYIString &	s,
		uint32_t	uPos,
		uint32_t	uLen = `std::numeric_limits< uint32_t >::max()`
	)

Inserts the incoming string s into the current string at character position uPos.

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

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

ConstIterator CYIString::Insert	(	const CYIString &	s,
		const ConstIterator &	insertPosition
	)

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

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.

bool CYIString::IsEmpty ( ) const

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

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

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() const

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.

int32_t CYIString::LastIndexOf	(	const CYIString &	s,
		uint32_t	uPos = `std::numeric_limits< uint32_t >::max()`
	)		const

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

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

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.

CYIString CYIString::Left ( uint32_t uLen ) const

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

CYIString::operator const char * ( ) const

Overloaded operator to make implicit casting easier.

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

Returns true if the s string is not equal to this string, false otherwise.

bool CYIString::operator!= ( const char * pUTF8 ) const

Returns true if the pUTF8 string is not equal to this string, false otherwise.

template<class T >

CYIString CYIString::operator+ ( T arg ) const

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

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

Appends the string s to the current string.

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.

bool CYIString::operator< ( const CYIString & s1 ) 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 string.

bool CYIString::operator<= ( const CYIString & s1 ) 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 string.

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

Assigns a copy of s to this string.

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.

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

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

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

Returns true if the s string is equal to this string, false otherwise.

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

Returns true if the pUTF8 string is equal to this string, false otherwise.

bool CYIString::operator> ( const CYIString & s1 ) 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 string.

bool CYIString::operator>= ( const CYIString & s1 ) 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 string.

char32_t CYIString::operator[] ( int32_t nPos ) const

Returns the 32-bit Unicode value at that character position specified by uPos. Cannot be modified.

CYIString& CYIString::Prepend ( const CYIString & s )

Prepends the incoming string s to the current string.

CYIString& CYIString::Prepend	(	const char *	pUTF8,
		uint32_t	uSizeBytes = `std::numeric_limits< uint32_t >::max()`
	)

Prepends the incoming string pUTF8 to the current string.

By default, this function expects a null-terminated array. The uSize 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.

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.

ConstReverseIterator CYIString::rbegin ( ) const

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

void CYIString::Remove ( const CYIString & text )

Remove all occurences of text from the current string.

ConstReverseIterator CYIString::rend ( ) const

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

CYIString& CYIString::Replace	(	const CYIString &	s,
		uint32_t	uPos,
		uint32_t	uLen
	)

Replaces a portion of the string from character position uPos for uLen characters with the s string.

If uPos is larger than the length of this string, the provided string is appended to this one. If uLen is longer than this string, the whole string is replaced by s.

ConstIterator CYIString::Replace	(	const CYIString &	s,
		const ConstIterator &	begin,
		const ConstIterator &	end
	)

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

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

CYIString& CYIString::Replace	(	const CYIString &	oldSubstring,
		const CYIString &	newSubstring,
		uint32_t	uMaximumReplacements = `std::numeric_limits< uint32_t >::max()`
	)

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

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

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

ConstReverseIterator CYIString::ReverseFind	(	const CYIString &	s,
		const ConstReverseIterator &	begin
	)		const

Returns the iterator pointing to the 'next' occurrence of 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 s is not found.

CYIString CYIString::Right ( uint32_t uLen ) const

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

std::vector<CYIString> CYIString::Split	(	const CYIString &	delimiter,
		bool	bIgnoreEmptySubstrings = `true`,
		uint32_t	uMaximumParts = `std::numeric_limits< uint32_t >::max()`
	)		const

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

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

The uMaximumParts parameter can be used to specify the maximum number of elements to return in the vector. When more than ( uMaximumParts - 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 uMaximumParts 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 bIgnoreEmptySubstrings is true, 'empty' substrings do not count towards the parts count.

bool CYIString::StartsWith	(	const CYIString &	s,
		CASE_MODE	eCaseSensitivity = `CASE_SENSITIVE`
	)		const

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

If a case-insenstive compare is needed, pass CASE_INSENSITIVE to the eCaseSensitivity parameter.

Note: Empty strings are 'found' at the beginning of every string.

CYIString CYIString::SubStr	(	uint32_t	uPos = `0`,
		uint32_t	uLen = `std::numeric_limits< uint32_t >::max()`
	)		const

Returns the sub-string of the current string from character position uPos for uLen characters. Returns an empty string in the case of invalid uPos or uLen values.

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

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

void CYIString::Swap ( CYIString & s )

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

template<class T >

T CYIString::To ( bool * pbError = 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, pbError, 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.

Sample usage:

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

bool CYIString::ToBool ( bool * pbError = 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, pbError, 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.

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.

double CYIString::ToDouble ( bool * pbError = 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, pbError, 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.

float CYIString::ToFloat ( bool * pbError = 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, pbError, 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.

CYIString CYIString::ToLower ( ) const

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

CYIString CYIString::ToNormalizedText ( bool * pbError = nullptr ) const

Returns a normalized copy of this string. A normalized string has had any combining characters composed into the equivalent unicode character(s).

Example: A CYIString containing "e´", ie. unicode {U+0065, U+0341} will result in "é" after normalization.

If any errors occurs, an unmodified copy of this string is returned. A pointer to a boolean, pbError, 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.

NSString* CYIString::ToNSString ( ) const

Returns the NSString representation of this string.

Note: Only available on Objective-C platforms.; If this string contains one or more null characters, the returned NSString will only contain data up to (and excluding) the first null character.

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

Returns the STL string representation of this string.

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.

U_NAMESPACE_QUALIFIER UnicodeString CYIString::ToUnicodeString ( ) const

Returns the ICU UnicodeString representation of this string.

CYIString CYIString::ToUpper ( ) const

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

std::unique_ptr<char16_t[]> CYIString::ToUTF16 ( uint32_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 uint32_t in pElementsCount.

std::unique_ptr<char32_t[]> CYIString::ToUTF32 ( uint32_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 uint32_t in pElementsCount.

std::unique_ptr<char[]> CYIString::ToUTF8 ( uint32_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 uint32_t in pElementsCount.

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

See also: GetData()

template<class T >

T CYIString::ToValue ( bool * pbError = 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, pbError, 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.

Sample usage:

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

See also: To(bool *) const

std::unique_ptr<wchar_t[]> CYIString::ToWideChars ( uint32_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 uint32_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.

void CYIString::Trim ( )

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

void CYIString::TrimLeft ( uint32_t uLen = std::numeric_limits< uint32_t >::max() )

Trims whitespace at the beginning of the string. The amount of removed whitespace can be limited using the uLen parameter.

void CYIString::TrimRight ( uint32_t uLen = std::numeric_limits< uint32_t >::max() )

Trims whitespace at the end of the string. The amount of removed whitespace can be limited using the uLen parameter.

Friends And Related Function Documentation

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

const CYIString CYIString::EMPTY_STRING

static

A static instance of an empty string. Useful for use in functions that return references.

Warning: Do not use in static context (e.g. to initialize a static member or as the return value of a static function).

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

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation