A flexible, reference counted, copy-on-write, thread-safe, nullable string. More...

#include <String.h++>

Collaboration diagram for String:

Public Types
typedef char16_t	value_type

typedef const char16_t *	const_iterator

Public Member Functions
	String ()
	Construct a new, empty string. More...

	String (const String &other)
	Copy constructor. More...

	String (char16_t *str, uint_t offset=0, uint_t count=0, bool copy=true)
	Construct a new string from a C string. More...

	String (const char16_t *str, uint_t offset=0, uint_t count=0)
	Construct a new string from an array of UTF-16 characters. More...

	String (const wchar_t *str)
	Construct a new string from a C wide string. More...

	String (const char *str, uint_t offset=0, uint_t count=0)
	Construct a new string from a C string encoded in UTF-8. More...

	~String ()
	Destructor. More...

bool	endsWith (const String &str, bool ignoreCase=false) const
	Test if the string ends with the given string. More...

bool	endsWith (const Char &c, bool ignoreCase=false) const
	Test if the string ends with the given character. More...

bool	endsWithAnyOf (const String &chars, bool ignoreCase=false) const
	Test if the string ends with any character in a given set of characters. More...

bool	startsWith (const String &str, bool ignoreCase=false) const
	Test if the string starts with the given string. More...

bool	startsWith (const Char &c, bool ignoreCase=false) const
	Test if the string starts with the given character. More...

bool	startsWithAnyOf (const String &chars, bool ignoreCase=false) const
	Test if the string starts with any character in a given set of characters. More...

uint_t	getLength () const
	Get the length of the string. More...

uint_t	length () const
	Get the length of the string. More...

void	setLength (uint_t length)
	Set the length of the string. More...

void	reserve (uint_t capacity)
	Reserve space in the string for the given number of characters. More...

uint_t	getCapacity () const
	Get the current capacity of the string, in characters. More...

void	compact ()
	Compact the string so that it occupies the minimum amount of memory required. More...

String &	clear ()
	Clear the string. More...

bool	isEmpty () const
	Test if the string is empty. More...

bool	isNull () const
	Test if the string is null. More...

bool	isInteger () const
	Test if the string holds an integer. More...

bool	isAlphaNumeric () const
	Test if the string consists solely of alphanumeric characters. More...

int	compareTo (const String &other, bool ignoreCase=false) const
	Compare the string to another. More...

String &	trim (const String &chars=whitespaceChars, bool begin=true, bool end=true)
	Trim leading and trailing characters from the string. More...

String &	trimBegin (const String &chars=whitespaceChars)
	Trim characters from the beginning of the string. More...

String &	trimEnd (const String &chars=whitespaceChars)
	Trim characters from the end of the string. More...

String &	chop (const Char &c)
	Truncate the string at the first occurrence of the given character. More...

String &	reverseChop (const Char &c)
	Truncate the string at the last occurrence of the given character. More...

String &	replace (const Char &a, const Char &b)
	Replace all occurences of one character with another. More...

String &	replace (const String &a, const String &b)
	Replace all occurences of one substring with another. More...

String &	insert (const Char &c, uint_t index=0)
	Insert a character into the string. More...

String &	insert (const String &str, uint_t index=0, uint_t length=0)
	Insert a string into this string. More...

String &	insert (const char16_t *str, uint_t index=0, uint_t count=0)
	Insert a UTF-16 character array into this string. More...

String &	insert (const wchar_t *str, uint_t index=0, uint_t count=0)
	Insert a C wide string to this string. More...

String &	insert (const char *str, uint_t index=0, uint_t count=0)
	Insert a C string to this string. More...

String &	append (bool v)
	Append a string representation of a boolean value to the end of the string. More...

String &	append (char c)
	Append a character to the end of the string. More...

String &	append (char16_t c)
	Append a UTF-16 character to the end of the string. More...

String &	append (int val)
	Append a string representation of an integer value onto the end of the string. More...

String &	append (int val, uint_t base)
	Append a string representation of an integer value in the given base onto the end of the string. More...

String &	append (uint_t val)
	Append a string representation of an unsigned integer value onto the end of the string. More...

String &	append (uint_t val, uint_t base)
	Append a string representation of an unsigned integer value in the given base onto the end of the string. More...

String &	append (const int64_t &val)
	Append a string representation of a long long (64-bit) integer onto the end of the string. More...

String &	append (const double &val, uint_t precision=6)
	Append a string representation of double-precision floating point value onto the end of the string. More...

String &	append (const uint64_t &val)
	Append a string representation of an unsigned long long (64-bit) integer onto the end of the string. More...

String &	append (const Char &c)
	Append a character to the end of the string. More...

String &	append (const String &str, uint_t count=0)
	Append a string to the end of the string. More...

String &	append (const char16_t *str, uint_t count=0)
	Append a UTF-16 character array to the end of the string. More...

String &	append (const char *str, uint_t count=0)
	Append a string to the end of the string. More...

String &	append (const wchar_t *str, uint_t count=0)
	Append a wide string to the end of the string. More...

String &	prepend (char c)
	Prepend a character to the beginning of the string. More...

String &	prepend (char16_t c)
	Prepend a character to the beginning of the string. More...

String &	prepend (const Char &c)
	Prepend a character to the beginning of the string. More...

String &	prepend (const String &str, uint_t count=0)
	Prepend a string to the beginning of the string. More...

String &	prepend (const char16_t *str, uint_t count=0)
	Prepend a string to the beginning of the string. More...

String &	prepend (const char *str, uint_t count=0)
	Prepend a string to the beginning of the string. More...

String &	prepend (const wchar_t *str, uint_t count=0)
	Prepend a wide string to the beginning of the string. More...

String &	remove (uint_t fromIndex, uint_t toIndex=END)
	Remove a portion of the string. More...

Char	charAt (uint_t index) const
	Return the character at the given index. More...

String &	setCharAt (uint_t index, const Char &c)
	Set the character at the given index. More...

uint_t	hash (uint_t modulo=256) const
	Compute a hashcode for the string. More...

String	substring (uint_t fromIndex, uint_t toIndex=END) const
	Extract a substring from the string. More...

int	indexOf (const Char &c, uint_t fromIndex=0) const
	Find the first occurrence of a given character in the string. More...

int	indexOf (const char *str, uint_t fromIndex=0) const
	Find the first occurrence of a given string in this string. More...

int	indexOfAnyOf (const String &chars, uint_t fromIndex=0) const
	Find the first occurrence in this string of any character in a set of characters. More...

int	indexOf (const String &str, uint_t fromIndex=0) const
	Find the first occurrence of a given string in this string. More...

int	lastIndexOf (const Char &c, uint_t fromIndex=END) const
	Find the last occurrence of a given character in this string. More...

int	lastIndexOfAnyOf (const String &chars, uint_t fromIndex=END) const
	Find the last occurrence in the string of any character in a set of characters. More...

int	lastIndexOf (const String &str, uint_t fromIndex=END) const
	Find the last occurrence of a given string in this string. More...

bool	contains (const Char &c) const
	Determine if the string contains a given character. More...

bool	contains (const String &str) const
	Determine if the string contains a given substring. More...

bool	containsAnyOf (const char *chars) const
	Determine if the string contains any character in a given set of characters. More...

String	nextToken (uint_t &fromIndex, const String &delim=whitespaceChars) const
	Extract a token from the string. More...

uint_t	split (StringVec &tokens, const String &delim=whitespaceChars, uint_t limit=0) const
	Split the string into a series of tokens, without modifying the string. More...

String &	toLowerCase ()
	Convert the string to lower case. More...

String &	toUpperCase ()
	Convert the string to upper case. More...

String &	fill (const Char &c, uint_t count)
	Fill the string with a character. More...

String &	pad (const Char &c, uint_t count)
	Pad the string with a character. More...

bool	toBool (uint_t index=0) const
	Parse a boolean value from the string. More...

int	toInt (uint_t index=0, uint_t base=10) const
	Parse an integer from the string. More...

uint_t	toUInt (uint_t index=0, uint_t base=10) const
	Parse an unsigned integer from the string. More...

int64_t	toInt64 (uint_t index=0, uint_t base=10) const
	Parse a 64-bit integer from the string. More...

uint64_t	toUInt64 (uint_t index=0, uint_t base=10) const
	Parse an unsigned 64-bit integer from the string. More...

float	toFloat (uint_t index=0) const
	Parse a floating point value from the string. More...

double	toDouble (uint_t index=0) const
	Parse a double precision floating point value from the string. More...

	operator const void * () const
	Pointer cast operator. More...

const char16_t *	data () const
	Returns a pointer to the UTF-16 data for this string. More...

CString	toUTF8 () const
	Return the contents of the string as an immutable C string. More...

String &	operator= (const char *other)
	Assignment operator. More...

String &	operator= (const wchar_t *other)
	Assignment operator. More...

String &	operator= (const String &other)
	Assignment operator. More...

String &	operator= (const std::string &other)
	Assignment operator. More...

CharRef	operator[] (int index)
	Array index operator. More...

const Char	operator[] (int index) const
	Array index operator. More...

const_iterator	begin () const
	Return a const_iterator to the beginning of the string. More...

const_iterator	end () const
	Return a const_iterator to the end of the string. More...

String	operator() (uint_t fromIndex, uint_t toIndex=END) const
	Substring operator. More...

bool	operator! () const
	Unary NOT operator. More...

String &	operator+= (char c)
	Append a character onto the end of the string. More...

String &	operator+= (char16_t c)
	Append a UTF-16 character onto the end of the string. More...

String &	operator+= (const Char &c)
	Append a character onto the end of the string. More...

String &	operator+= (const char *str)
	Append a C string onto the end of this string. More...

String &	operator+= (const String &str)
	Append a string onto the end of this string. More...

String &	operator+= (bool val)
	Append a string representation of a boolean value onto the end of the string. More...

String &	operator+= (int val)
	Append a string representation of an integer value onto the end of the string. More...

String &	operator+= (uint_t val)
	Append a string representation of an unsigned integer value onto the end of the string. More...

String &	operator+= (double val)
	Append a string representation of double-precision floating point value onto the end of the string. More...

String &	operator+= (int64_t val)
	Append a string representation of a long long (64-bit) integer onto the end of the string. More...

String &	operator+= (uint64_t val)
	Append a string representation of an unsigned long long (64-bit) integer onto the end of the string. More...

String &	operator<< (const char *str)
	Append operator. More...

String &	operator<< (const wchar_t *str)
	Append operator. More...

String &	operator<< (const String &str)
	Append operator. More...

String &	operator<< (bool val)
	Append operator. More...

String &	operator<< (char c)
	Append operator. More...

String &	operator<< (char16_t c)
	Append operator. More...

String &	operator<< (const Char &c)
	Append operator. More...

String &	operator<< (int val)
	Append operator. More...

String &	operator<< (uint_t val)
	Append operator. More...

String &	operator<< (const int64_t &val)
	Append operator. More...

String &	operator<< (const uint64_t &val)
	Append operator. More...

String &	operator<< (const double &val)
	Append operator. More...

String &	operator^= (char c)
	Prepend operator. More...

String &	operator^= (char16_t c)
	Prepend operator. More...

String &	operator^= (const Char &c)
	Prepend operator. More...

String &	operator^= (const char *str)
	Prepend operator. More...

String &	operator^= (const wchar_t *str)
	Prepend operator. More...

String &	operator^= (const String &str)
	Prepend operator. More...

String	operator+ (const String &str)

String	operator+ (const char *str)

String	operator+ (const Char &c)

void	write (std::ostream &stream) const
	Write the string (in UTF-8 form) to a stream. More...

Static Public Attributes
static const uint_t	END = ~0
	A pseudo-index indicating the end of the string. More...

static const String	null = String()
	The null string. More...

static const String	nullRep = String("(null)")
	The string representation of the null value. More...

static const String	empty = ""
	The empty string. More...

static const String	whitespaceChars = " \t\f\r\n\v"
	The set of whitespace delimiter characters. More...

Detailed Description

A flexible, reference counted, copy-on-write, thread-safe, nullable string.

Author: Mark Lindner

Member Typedef Documentation

◆ const_iterator

typedef const char16_t* const_iterator

◆ value_type

typedef char16_t value_type

Constructor & Destructor Documentation

◆ String() [1/6]

String ( )

Construct a new, empty string.

◆ String() [2/6]

String ( const String & other )

Copy constructor.

Parameters

other The string to copy.

◆ String() [3/6]

String	(	char16_t *	str,
		uint_t	offset = `0`,
		uint_t	count = `0`,
		bool	copy = `true`
	)

Construct a new string from a C string.

Parameters

str	The C string to copy or inherit.
offset	The number of characters from the beginning of the string to skip over.
count	The number of characters from the offset to use, or 0 to use all the characters to the end of the string.
copy	If true, the C string is copied into the String; otherwise the C string is inherited and the length parameter is ignored.

◆ String() [4/6]

String	(	const char16_t *	str,
		uint_t	offset = `0`,
		uint_t	count = `0`
	)

Construct a new string from an array of UTF-16 characters.

The array is copied into the string.

Parameters

str	The character array.
offset	The number of characters from the beginning of the string to skip over.
count	The number of characters from the offset to use, or 0 to use all the characters to the end of the string.

◆ String() [5/6]

String ( const wchar_t * str )

Construct a new string from a C wide string.

Parameters

str	The C wide string.

Exceptions

EncodingException If the string contains invalid code points.

◆ String() [6/6]

String	(	const char *	str,
		uint_t	offset = `0`,
		uint_t	count = `0`
	)

Construct a new string from a C string encoded in UTF-8.

Parameters

str	The C string.
offset	The number of characters from the beginning of the string to skip over.
count	The number of characters from the offset to use, or 0 to use all the characters to the end of the string.

Exceptions

EncodingException If the string does not contain valid UTF-8.

◆ ~String()

~String ( )

Destructor.

Member Function Documentation

◆ append() [1/15]

String & append ( bool v )

Append a string representation of a boolean value to the end of the string.

Parameters

v	The value to append.

◆ append() [2/15]

String& append ( char c )

inline

Append a character to the end of the string.

Parameters

c	The character to append.

◆ append() [3/15]

String& append ( char16_t c )

inline

Append a UTF-16 character to the end of the string.

Parameters

c	The character to append.

◆ append() [4/15]

String & append ( int val )

Append a string representation of an integer value onto the end of the string.

Parameters

val	The value to append.

◆ append() [5/15]

String & append	(	int	val,
		uint_t	base
	)

Append a string representation of an integer value in the given base onto the end of the string.

Parameters

val	The value to append.
base	The numerical base in which to output the value. The valid range is 2 - 36, inclusive.

◆ append() [6/15]

String & append ( uint_t val )

Append a string representation of an unsigned integer value onto the end of the string.

Parameters

val	The value to append.

◆ append() [7/15]

String & append	(	uint_t	val,
		uint_t	base
	)

Append a string representation of an unsigned integer value in the given base onto the end of the string.

Parameters

val	The value to append.
base	The numerical base in which to output the value. The valid range is 2 - 36, inclusive.

◆ append() [8/15]

String & append ( const int64_t & val )

Append a string representation of a long long (64-bit) integer onto the end of the string.

Parameters

val	The value to append.

◆ append() [9/15]

String & append	(	const double &	val,
		uint_t	precision = `6`
	)

Append a string representation of double-precision floating point value onto the end of the string.

Parameters

val	The value to append.
precision	The precision (the number of digits to include after the radix).

◆ append() [10/15]

String & append ( const uint64_t & val )

Append a string representation of an unsigned long long (64-bit) integer onto the end of the string.

Parameters

val	The value to append.

◆ append() [11/15]

String& append ( const Char & c )

inline

Append a character to the end of the string.

Parameters

c	The character to append.

◆ append() [12/15]

String& append	(	const String &	str,
		uint_t	count = `0`
	)

inline

Append a string to the end of the string.

Parameters

str	The character to append.
count	The maximum number of characters from str to append, or 0 to append all of str.

◆ append() [13/15]

String& append	(	const char16_t *	str,
		uint_t	count = `0`
	)

inline

Append a UTF-16 character array to the end of the string.

Parameters

str	The character array to append.
count	The maximum number of characters from str to append, or 0 to append all of str.

◆ append() [14/15]

String& append	(	const char *	str,
		uint_t	count = `0`
	)

inline

Append a string to the end of the string.

Parameters

str	The string to append.
count	The maximum number of characters from str to append, or 0 to append all of str.

◆ append() [15/15]

String& append	(	const wchar_t *	str,
		uint_t	count = `0`
	)

inline

Append a wide string to the end of the string.

Parameters

str	The string to append.
count	The maximum number of characters from str to append, or 0 to append all of str.

◆ begin()

String::const_iterator begin ( ) const

Return a const_iterator to the beginning of the string.

Exceptions

NullPointerException If the string is null.

◆ charAt()

Char charAt ( uint_t index ) const

Return the character at the given index.

Parameters

index The index.

Returns: The character at the given index.

Exceptions

OutOfBoundsException If index is out of range.

◆ chop()

String & chop ( const Char & c )

Truncate the string at the first occurrence of the given character.

Parameters

c	The character at which to truncate.

Returns: The string.

◆ clear()

String& clear ( )

inline

Clear the string.

Sets the length of the string to 0.

Returns: The string.

◆ compact()

void compact ( )

Compact the string so that it occupies the minimum amount of memory required.

◆ compareTo()

int compareTo	(	const String &	other,
		bool	ignoreCase = `false`
	)		const

Compare the string to another.

Parameters

other	The string to compare to.
ignoreCase	A flag indicating whether the compare should be case insensitive.

Returns: A negative value if the string is lexicographically "less" than other, a positive value if it is "greater" than other, and 0 if they are "equal".

◆ contains() [1/2]

bool contains ( const Char & c ) const

inline

Determine if the string contains a given character.

Parameters

c	The character to search for.

Returns: true if the string contains at least one occurrence of the character, false otherwise.

◆ contains() [2/2]

bool contains ( const String & str ) const

inline

Determine if the string contains a given substring.

Parameters

str	The substring to search for.

Returns: true if the string contains at least one occurrence of the substring, false otherwise.

◆ containsAnyOf()

bool containsAnyOf ( const char * chars ) const

inline

Determine if the string contains any character in a given set of characters.

Parameters

chars The set of characters.

Returns: true if the string contains at least one occurrence of any character in the set, false otherwise.

◆ data()

const char16_t * data ( ) const

Returns a pointer to the UTF-16 data for this string.

◆ end()

String::const_iterator end ( ) const

Return a const_iterator to the end of the string.

Exceptions

NullPointerException If the string is null.

◆ endsWith() [1/2]

bool endsWith	(	const String &	str,
		bool	ignoreCase = `false`
	)		const

Test if the string ends with the given string.

Parameters

str	The other string.
ignoreCase	A flag indicating whether the comparison should be case-insensitive.

Returns: true if this string ends with str, false otherwise.

◆ endsWith() [2/2]

bool endsWith	(	const Char &	c,
		bool	ignoreCase = `false`
	)		const

Test if the string ends with the given character.

Parameters

c	The character.
ignoreCase	A flag indicating whether the comparison should be case-insensitive.

Returns: true if the string ends with c, false otherwise.

◆ endsWithAnyOf()

bool endsWithAnyOf	(	const String &	chars,
		bool	ignoreCase = `false`
	)		const

Test if the string ends with any character in a given set of characters.

Parameters

chars	The set of characters.
ignoreCase	A flag indicating whether the comparison should be case-insensitive.

Returns: true if the string ends with one of the characters in the set, false otherwise.

◆ fill()

String & fill	(	const Char &	c,
		uint_t	count
	)

Fill the string with a character.

Parameters

c	The fill character.
count	The number of characters to fill.

◆ getCapacity()

uint_t getCapacity ( ) const

Get the current capacity of the string, in characters.

This value takes into account the space required for the final NUL terminator.

◆ getLength()

uint_t getLength ( ) const

Get the length of the string.

Returns: The length, in characters, or 0 if the String is null.

◆ hash()

uint_t hash ( uint_t modulo = 256 ) const

Compute a hashcode for the string.

Parameters

modulo The desired range for the hashcode.

Returns: A hashcode in the range [0, modulo).

◆ indexOf() [1/3]

int indexOf	(	const Char &	c,
		uint_t	fromIndex = `0`
	)		const

Find the first occurrence of a given character in the string.

Parameters

c	The character to search for.
fromIndex	The start index from which to begin searching.

Returns: The index of the first occurrence of the character, or -1 if the character was not found.

◆ indexOf() [2/3]

int indexOf	(	const char *	str,
		uint_t	fromIndex = `0`
	)		const

inline

Find the first occurrence of a given string in this string.

Parameters

str	The string to search for.
fromIndex	The start index from which to begin searching.

Returns: The index of the first occurrence of the string, or -1 if the string was not found.

◆ indexOf() [3/3]

int indexOf	(	const String &	str,
		uint_t	fromIndex = `0`
	)		const

Find the first occurrence of a given string in this string.

Parameters

str	The string to search for.
fromIndex	The start index from which to begin searching.

Returns: The index of the first occurrence of the string, or -1 if the string was not found.

◆ indexOfAnyOf()

int indexOfAnyOf	(	const String &	chars,
		uint_t	fromIndex = `0`
	)		const

Find the first occurrence in this string of any character in a set of characters.

Parameters

chars	The set of characters search for.
fromIndex	The start index from which to begin searching.

Returns: The index of the first occurrence of any character in the set, or -1 if no occurrence was not found.

◆ insert() [1/5]

String & insert	(	const Char &	c,
		uint_t	index = `0`
	)

Insert a character into the string.

Parameters

c	The character to insert.
index	The index at which to insert the character. If the index is out of range, the character is appended to the end of the string.

◆ insert() [2/5]

String & insert	(	const String &	str,
		uint_t	index = `0`,
		uint_t	length = `0`
	)

Insert a string into this string.

Parameters

str	The string to insert.
index	The index at which to insert the string. If the index is out of range, the string is appended to the end of this string.
length	The maximum number of characters from str to insert.

◆ insert() [3/5]

String & insert	(	const char16_t *	str,
		uint_t	index = `0`,
		uint_t	count = `0`
	)

Insert a UTF-16 character array into this string.

Parameters

str	The array to insert.
index	The index at which to insert the characters. If the index is out of range, the characters are appended to the end of this string.
count	The number of characters from str to insert.

◆ insert() [4/5]

String& insert	(	const wchar_t *	str,
		uint_t	index = `0`,
		uint_t	count = `0`
	)

inline

Insert a C wide string to this string.

Parameters

str	The C wide string to insert.
index	The index at which to insert the string. If the index is out of range, the string is appended to the end of this string.
count	The maximum number of characters from str to insert.

◆ insert() [5/5]

String& insert	(	const char *	str,
		uint_t	index = `0`,
		uint_t	count = `0`
	)

inline

Insert a C string to this string.

Parameters

str	The C wide string to insert.
index	The index at which to insert the string. If the index is out of range, the string is appended to the end of this string.
count	The maximum number of characters from str to insert.

◆ isAlphaNumeric()

bool isAlphaNumeric ( ) const

Test if the string consists solely of alphanumeric characters.

Returns: true if the string is alphanumeric, false otherwise.

◆ isEmpty()

bool isEmpty ( ) const

Test if the string is empty.

Returns: true if the string is null or has length 0, false otherwise.

◆ isInteger()

bool isInteger ( ) const

Test if the string holds an integer.

For example, "123", "+5", and "-123" are integers.

Returns: true if the string is an integer, false otherwise.

◆ isNull()

bool isNull ( ) const

Test if the string is null.

Returns: true if the string is null, false otherwise.

◆ lastIndexOf() [1/2]

int lastIndexOf	(	const Char &	c,
		uint_t	fromIndex = `END`
	)		const

Find the last occurrence of a given character in this string.

Parameters

c	The character to search for.
fromIndex	The index from which to begin searching backwards, or END to start at the end of the string.

Returns: The index of the last occurrence of the character, or -1 if the character was not found.

◆ lastIndexOf() [2/2]

int lastIndexOf	(	const String &	str,
		uint_t	fromIndex = `END`
	)		const

Find the last occurrence of a given string in this string.

Parameters

str	The string to search for.
fromIndex	The index from which to begin searching backwards, or END to start at the end of the string.

Returns: The index of the last occurrence of the string, or -1 if the string was not found.

◆ lastIndexOfAnyOf()

int lastIndexOfAnyOf	(	const String &	chars,
		uint_t	fromIndex = `END`
	)		const

Find the last occurrence in the string of any character in a set of characters.

Parameters

chars	The set of characters search for.
fromIndex	The index from which to begin searching backwards, or END to start at the end of the string.

Returns: The index of the last occurrence of any character in the set, or -1 if no occurrence was not found.

◆ length()

uint_t length ( ) const

inline

Get the length of the string.

Returns: The length, in characters, or 0 if the string is null.

◆ nextToken()

String nextToken	(	uint_t &	fromIndex,
		const String &	delim = `whitespaceChars`
	)		const

Extract a token from the string.

Parameters

fromIndex	The start index at which to begin searching for a token. Will be modified on return to point to one character past the extracted token.
delim	The set of possible token delimiter characters (the set of whitespace characters by default).

Returns: The extracted token, or String::null if the end of the string has been reached.

◆ operator const void *()

operator const void * ( ) const

Pointer cast operator.

◆ operator!()

bool operator! ( ) const

inline

Unary NOT operator.

Returns: true if the string is null, false otherwise.

◆ operator()()

String operator()	(	uint_t	fromIndex,
		uint_t	toIndex = `END`
	)		const

inline

Substring operator.

Extract a substring from the string.

Parameters

fromIndex	The start index of the substring.
toIndex	The end index of the substring, or END to indicate the end of the string.

Returns: The substring as a new string. If fromIndex and toIndex are equal, an empty string is returned.

◆ operator+() [1/3]

String operator+ ( const String & str )

◆ operator+() [2/3]

String operator+ ( const char * str )

◆ operator+() [3/3]

String operator+ ( const Char & c )

◆ operator+=() [1/11]

String& operator+= ( char c )

inline

Append a character onto the end of the string.

Parameters

c	The character to append.

◆ operator+=() [2/11]

String& operator+= ( char16_t c )

inline

Append a UTF-16 character onto the end of the string.

Parameters

c	The character to append.

◆ operator+=() [3/11]

String& operator+= ( const Char & c )

inline

Append a character onto the end of the string.

Parameters

c	The character to append.

◆ operator+=() [4/11]

String& operator+= ( const char * str )

inline

Append a C string onto the end of this string.

Parameters

str	The string to append.

◆ operator+=() [5/11]

String& operator+= ( const String & str )

inline

Append a string onto the end of this string.

Parameters

str	The string to append.

◆ operator+=() [6/11]

String& operator+= ( bool val )

inline

Append a string representation of a boolean value onto the end of the string.

Parameters

val	The value to append.

◆ operator+=() [7/11]

String& operator+= ( int val )

inline

Append a string representation of an integer value onto the end of the string.

Parameters

val	The value to append.

◆ operator+=() [8/11]

String& operator+= ( uint_t val )

inline

Append a string representation of an unsigned integer value onto the end of the string.

Parameters

val	The value to append.

◆ operator+=() [9/11]

String& operator+= ( double val )

inline

Append a string representation of double-precision floating point value onto the end of the string.

Parameters

val	The value to append.

◆ operator+=() [10/11]

String& operator+= ( int64_t val )

inline

Append a string representation of a long long (64-bit) integer onto the end of the string.

Parameters

val	The value to append.

◆ operator+=() [11/11]

String& operator+= ( uint64_t val )

inline

Append a string representation of an unsigned long long (64-bit) integer onto the end of the string.

Parameters

val	The value to append.

◆ operator=() [1/4]

String & operator= ( const char * other )

Assignment operator.

Exceptions

EncodingException If the input is not valid UTF-8.

◆ operator=() [2/4]

String & operator= ( const wchar_t * other )

Assignment operator.

Exceptions

EncodingException If the input contains invalid UTF-32 characters.

◆ operator=() [3/4]

String & operator= ( const String & other )

Assignment operator.

◆ operator=() [4/4]

String& operator= ( const std::string & other )

inline

Assignment operator.

Exceptions

EncodingException If the input is not valid UTF-8.

◆ operator[]() [1/2]

CharRef operator[] ( int index )

Array index operator.

Obtain a reference to the character at the given offset in the string.

Parameters

index The index.

Returns: A reference to the character at the specified index.

Exceptions

OutOfBoundsException If index is out of range.

◆ operator[]() [2/2]

const Char operator[] ( int index ) const

Array index operator.

Obtain a copy of the character at the given offset in the string.

Parameters

index The index.

Returns: The character at the specified index, as a Char.

inline

Prepend operator.

◆ pad()

String & pad	(	const Char &	c,
		uint_t	count
	)

Pad the string with a character.

Parameters

c	The pad character.
count	The number of characters to pad.

◆ prepend() [1/7]

String& prepend ( char c )

inline

Prepend a character to the beginning of the string.

Parameters

c	The character to prepend.

◆ prepend() [2/7]

String& prepend ( char16_t c )

inline

Prepend a character to the beginning of the string.

Parameters

c	The character to prepend.

◆ prepend() [3/7]

String& prepend ( const Char & c )

inline

Prepend a character to the beginning of the string.

Parameters

c	The character to prepend.

◆ prepend() [4/7]

String& prepend	(	const String &	str,
		uint_t	count = `0`
	)

inline

Prepend a string to the beginning of the string.

Parameters

str	The character to prepend.
count	The maximum number of characters from str to prepend, or 0 to prepend all of str.

◆ prepend() [5/7]

String& prepend	(	const char16_t *	str,
		uint_t	count = `0`
	)

inline

Prepend a string to the beginning of the string.

Parameters

str	The character to prepend.
count	The maximum number of characters from str to prepend, or 0 to prepend all of str.

◆ prepend() [6/7]

String& prepend	(	const char *	str,
		uint_t	count = `0`
	)

inline

Prepend a string to the beginning of the string.

Parameters

str	The character to prepend.
count	The maximum number of characters from str to prepend, or 0 to prepend all of str.

◆ prepend() [7/7]

String& prepend	(	const wchar_t *	str,
		uint_t	count = `0`
	)

inline

Prepend a wide string to the beginning of the string.

Parameters

str	The character to prepend.
count	The maximum number of characters from str to prepend, or 0 to prepend all of str.

◆ remove()

String & remove	(	uint_t	fromIndex,
		uint_t	toIndex = `END`
	)

Remove a portion of the string.

Parameters

fromIndex	The start index of the range to remove.
toIndex	The end index of the range to remove, or END to remove to the end of the string.

◆ replace() [1/2]

String & replace	(	const Char &	a,
		const Char &	b
	)

Replace all occurences of one character with another.

Parameters

a	The character to replace.
b	The replacement character.

Returns: The string.

◆ replace() [2/2]

String & replace	(	const String &	a,
		const String &	b
	)

Replace all occurences of one substring with another.

Parameters

a	The substring to replace.
b	The replacement substring.

Returns: The string.

◆ reserve()

void reserve ( uint_t capacity )

Reserve space in the string for the given number of characters.

If the new capacity is less than or equal to the current capacity, the string is not modified.

Parameters

capacity The new capacity.

◆ reverseChop()

String & reverseChop ( const Char & c )

Truncate the string at the last occurrence of the given character.

Parameters

c	The character at which to truncate.

Returns: The string.

◆ setCharAt()

String & setCharAt	(	uint_t	index,
		const Char &	c
	)

Set the character at the given index.

Parameters

index	The index.
c	The character to set.

Exceptions

OutOfBoundsException If index is out of range.

◆ setLength()

void setLength ( uint_t length )

Set the length of the string.

Allows the string to be truncated to an arbitrary length.

Parameters

length The new length. The new length must be less than the current length; otherwise the string is left unmodified.

◆ split()

uint_t split	(	StringVec &	tokens,
		const String &	delim = `whitespaceChars`,
		uint_t	limit = `0`
	)		const

Split the string into a series of tokens, without modifying the string.

Parameters

tokens	The vector in which to place the extracted tokens. If a non-empty vector is supplied, the tokens are added to the end of the vector.
delim	The set of possible token delimiter characters (the set of whitespace characters by default).
limit	The maximum number of tokens to extract, or 0 for no limit (the default).

Returns: The number of tokens extracted.

◆ startsWith() [1/2]

bool startsWith	(	const String &	str,
		bool	ignoreCase = `false`
	)		const

Test if the string starts with the given string.

Parameters

str	The other string.
ignoreCase	A flag indicating whether the comparison should be case-insensitive.

Returns: true if the String begins with str, false otherwise.

◆ startsWith() [2/2]

bool startsWith	(	const Char &	c,
		bool	ignoreCase = `false`
	)		const

Test if the string starts with the given character.

Parameters

c	The character.
ignoreCase	A flag indicating whether the comparison should be case-insensitive.

Returns: true if the string begins with c, false otherwise.

◆ startsWithAnyOf()

bool startsWithAnyOf	(	const String &	chars,
		bool	ignoreCase = `false`
	)		const

Test if the string starts with any character in a given set of characters.

Parameters

chars	The set of characters.
ignoreCase	A flag indicating whether the comparison should be case-insensitive.

Returns: true if the string starts with one of the characters in the set, false otherwise.

◆ substring()

String substring	(	uint_t	fromIndex,
		uint_t	toIndex = `END`
	)		const

Extract a substring from the string.

Parameters

fromIndex	The start index of the substring.
toIndex	The end index of the substring, or END to indicate the end of the string.

Returns: The substring as a new string. If fromIndex and toIndex are equal, an empty string is returned.

◆ toBool()

bool toBool ( uint_t index = 0 ) const

Parse a boolean value from the string.

Parameters

index The index to begin parsing at.

Returns: The parsed value.

◆ toDouble()

double toDouble ( uint_t index = 0 ) const

Parse a double precision floating point value from the string.

Parameters

index The index to begin parsing at.

Returns: The parsed value.

◆ toFloat()

float toFloat ( uint_t index = 0 ) const

Parse a floating point value from the string.

Parameters

index The index to begin parsing at.

Returns: The parsed value.

◆ toInt()

int toInt	(	uint_t	index = `0`,
		uint_t	base = `10`
	)		const

Parse an integer from the string.

Parameters

index	The index to begin parsing at.
base	The base (2 - 36).

Returns: The parsed value.

◆ toInt64()

int64_t toInt64	(	uint_t	index = `0`,
		uint_t	base = `10`
	)		const

Parse a 64-bit integer from the string.

Parameters

index	The index to begin parsing at.
base	The base (2 - 36).

Returns: The parsed value.

◆ toLowerCase()

String & toLowerCase ( )

Convert the string to lower case.

◆ toUInt()

uint_t toUInt	(	uint_t	index = `0`,
		uint_t	base = `10`
	)		const

Parse an unsigned integer from the string.

Parameters

index	The index to begin parsing at.
base	The base (2 - 36).

Returns: The parsed value.

◆ toUInt64()

uint64_t toUInt64	(	uint_t	index = `0`,
		uint_t	base = `10`
	)		const

Parse an unsigned 64-bit integer from the string.

Parameters

index	The index to begin parsing at.
base	The base (2 - 36).

Returns: The parsed value.

◆ toUpperCase()

String & toUpperCase ( )

Convert the string to upper case.

◆ toUTF8()

CString toUTF8 ( ) const

Return the contents of the string as an immutable C string.

◆ trim()

String & trim	(	const String &	chars = `whitespaceChars`,
		bool	begin = `true`,
		bool	end = `true`
	)

Trim leading and trailing characters from the string.

Returns: The string.

◆ trimBegin()

String& trimBegin ( const String & chars = whitespaceChars )

inline

Trim characters from the beginning of the string.

Parameters

chars The set of characters to trim (the set of whitespace characters by default).

◆ trimEnd()

String& trimEnd ( const String & chars = whitespaceChars )

inline

const String whitespaceChars = " \t\f\r\n\v"

static

The set of whitespace delimiter characters.

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

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ value_type

Constructor & Destructor Documentation

◆ String() [1/6]

◆ String() [2/6]

◆ String() [3/6]

◆ String() [4/6]

◆ String() [5/6]

◆ String() [6/6]

◆ ~String()

Member Function Documentation

◆ append() [1/15]

◆ append() [2/15]

◆ append() [3/15]

◆ append() [4/15]

◆ append() [5/15]

◆ append() [6/15]

◆ append() [7/15]

◆ append() [8/15]

◆ append() [9/15]

◆ append() [10/15]

◆ append() [11/15]

◆ append() [12/15]

◆ append() [13/15]

◆ append() [14/15]

◆ append() [15/15]

◆ begin()

◆ charAt()

◆ chop()

◆ clear()

◆ compact()

◆ compareTo()

◆ contains() [1/2]

◆ contains() [2/2]

◆ containsAnyOf()

◆ data()

◆ end()

◆ endsWith() [1/2]

◆ endsWith() [2/2]

◆ endsWithAnyOf()

◆ fill()

◆ getCapacity()

◆ getLength()

◆ hash()

◆ indexOf() [1/3]

◆ indexOf() [2/3]

◆ indexOf() [3/3]

◆ indexOfAnyOf()

◆ insert() [1/5]

◆ insert() [2/5]

◆ insert() [3/5]

◆ insert() [4/5]

◆ insert() [5/5]

◆ isAlphaNumeric()

◆ isEmpty()

◆ isInteger()

◆ isNull()

◆ lastIndexOf() [1/2]

◆ lastIndexOf() [2/2]

◆ lastIndexOfAnyOf()

◆ length()

◆ nextToken()

◆ operator const void *()

◆ operator!()

◆ operator()()

◆ operator+() [1/3]

◆ operator+() [2/3]

◆ operator+() [3/3]

◆ operator+=() [1/11]

◆ operator+=() [2/11]

◆ operator+=() [3/11]

◆ operator+=() [4/11]

◆ operator+=() [5/11]

◆ operator+=() [6/11]

◆ operator+=() [7/11]