String Class Reference

#include <string.h>

Inheritance diagram for String:

Detailed Description

Class to store unicode strings. String stores unicode characters. Any unicode characters are legal, including 0C (strings are not null-terminated). Strings are reference-counted objects. This means that as long as you copy and do not modify strings they are just referenced. The first modification breaks the link and it becomes a unique new object.

Error handling for String For convenience the String class has a relaxed out of memory handling, for example String("Example", 7) might fail, but since it's a constructor there's no Result returned. The same goes for String a += b; In most cases this is no problem at all: If for example you want to concatenate a file url and this fails then loading the file will fail anyway. Nonetheless there cases where you must ensure that a string operation has succeeded. To enable this for methods, operators or constructor which are not returning a Result but modify the String (are non-const) the internal reference will be set to a nullptr on allocation failure. And this can be checked using iferr, iferr_return (or even GetPointer() would work). For example:

String x = String(cstr, strlen(cstr)) iferr_return;
String y = "example"_s iferr_return;
x.Append(y) iferr_return;
(x += y) iferr_return;
x = (x + y) iferr_return;
String z = x.GetPart(0, 1) iferr_return;

Note

For + or += you have to enclose the expression in brackets, otherwise iferr_return will check the wrong term.

Error detection does not work for concatenated operations, e.g. for x.Append(y).Append(z) you cannot detect an error, the same goes for x = x + y + z;

Classes
class	StringIterator

Public Types
using	CharType = StringInterface::CharType
using	ValueType = Utf32Char
using	ConstIterator = StringIterator
using	Iterator = ConstIterator

Public Member Functions
	MAXON_DEFAULT_REFERENCE_CONSTRUCTORS (String, Reference)
	String (const Char *str, Int count, const StringDecodingRef &stringDecoding=GetUtf8DefaultDecoder())
	String (const Char *str, const StringDecodingRef &stringDecoding=GetUtf8DefaultDecoder())
	String (const Block< const Char > &str, const StringDecodingRef &stringDecoding=GetUtf8DefaultDecoder())
	String (const CString &str, const StringDecodingRef &stringDecoding=GetUtf8DefaultDecoder())
	String (const Utf32Char *str, Int count)
	String (const Block< const Utf32Char > &str)
	String (const Utf16Char *str, Int count)
	String (Int count, Utf32Char fillChar)
	String (const Id &prefix, const void *ptr)
	String (const String &prefix, const void *ptr, Bool prefix0x=true)
Utf32Char	operator[] (Int pos) const
MAXON_ATTRIBUTE_FORCE_INLINE StringInterface::CharPtr	operator[] (Int position)
ConstIterator	Begin () const
ConstIterator	End () const
Bool	IsEmpty () const
Bool	IsPopulated () const
String &	operator+= (const String &str)

Static Public Member Functions
static const String &	GetLineEnd ()

Private Member Functions
void	operator-> () const

Member Typedef Documentation

CharType

using CharType = StringInterface::CharType

ValueType

using ValueType = Utf32Char

ConstIterator

using ConstIterator = StringIterator

Iterator

using Iterator = ConstIterator

Constructor & Destructor Documentation

String() [1/10]

String ( const Char *  str, Int  count, const StringDecodingRef &  stringDecoding = GetUtf8DefaultDecoder()  )

explicit

Constructor from Char array. If you have static strings use "..."_s instead.

Parameters

[in]	str	C string block.
[in]	count	Number of characters, -1 to auto detect the length of the string (search for the first 0).
[in]	stringDecoding	Encoding type.

String() [2/10]

String ( const Char *  str, const StringDecodingRef &  stringDecoding = GetUtf8DefaultDecoder()  )

explicit

Constructor from Char array. If you have static strings use "..."_s instead.

Parameters

[in]	str	C string block.
[in]	stringDecoding	Encoding type.

String() [3/10]

String ( const Block< const Char > &  str, const StringDecodingRef &  stringDecoding = GetUtf8DefaultDecoder()  )

explicit

Constructor from a Char Block. If you have static strings use "..."_s instead.

Parameters

[in]	str	Char block, for example a BaseArray<Char>.
[in]	stringDecoding	Encoding type.

String() [4/10]

String ( const CString &  str, const StringDecodingRef &  stringDecoding = GetUtf8DefaultDecoder()  )

explicit

Constructor from CString.

Parameters

[in]	str	CString.
[in]	stringDecoding	Encoding type.

String() [5/10]

String ( const Utf32Char *  str, Int  count  )

explicit

Constructor from UTF-32 Utf32Char array. If you have static character strings use "..."_s instead.

Parameters

[in]	str	UTF-32 character block.
[in]	count	Number of characters, -1 to auto detect the length of the string (search for the first 0).

String() [6/10]

String ( const Block< const Utf32Char > &  str )

explicit

Constructor from UTF-32 Utf32Char Block.

Parameters

[in]

str

UTF-32 character block.

String() [7/10]

String ( const Utf16Char *  str, Int  count  )

explicit

Constructor from UTF-16 Utf16Char array.

Parameters

[in]	str	UTF-16 character block.
[in]	count	Number of characters, -1 to auto detect the length of the string (search for the first 0).

String() [8/10]

String ( Int  count, Utf32Char  fillChar  )

explicit

Constructor to create a string with a specific length and a default character.

Parameters

[in]	count	Number of characters of the new string.
[in]	fillChar	Character to fill the string with.

String() [9/10]

String	(	const Id &	prefix,
		const void *	ptr
	)

Constructs a string consisting of #prefix followed by an @ sign and the hex-formatted ptr.

Parameters

[in]	prefix	The prefix for the string.
[in]	ptr	A pointer.

String() [10/10]

String	(	const String &	prefix,
		const void *	ptr,
		Bool	prefix0x = true
	)

Constructor to create a string from a prefix and pointer address as hexadecimal text.

Parameters

[in]	prefix	The prefix string.
[in]	ptr	The pointer that will be added as hexadecimal text.
[in]	prefix0x	If true the pointer will start with '0x'.

Member Function Documentation

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS()

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS	(	String	,
		Reference
	)

operator[]() [1/2]

Utf32Char operator[]

(

Int

pos

)

const

Index operator to access single characters of the string.

Parameters

[in]

pos

Position within the string the first character starts with an index of 0. If the position is out of boundaries 0 will be returned.

Returns

Utf32Char for read (right of =), Utf32Char& for write (left of =).

operator[]() [2/2]

MAXON_ATTRIBUTE_FORCE_INLINE StringInterface::CharPtr operator[]

(

Int

position

)

Index operator to access single characters of the string.

Parameters

[in]

position

Position within the string the first character starts with an index of 0. if the position is out of boundaries no changes will be made.

Returns

Utf32Char for read (right of =), Utf32Char& for write (left of =).

Begin()

ConstIterator Begin

(

)

const

Returns and iterator pointing to the first character of this string.

Returns

Iterator for first character.

End()

ConstIterator End

(

)

const

Returns and iterator pointing to the end of this string (one behind last character).

Returns

Iterator for the end.

IsEmpty()

Bool IsEmpty

(

)

const

Returns if the string length is zero.

Returns

True if the string doesn't contain any character, or if it is a nullptr.

IsPopulated()

Bool IsPopulated

(

)

const

Returns if the string contains any characters.

Returns

True if the string contains any character.

operator+=()

String& operator+=

(

const String &

str

)

Appends str at the end of this string.

Parameters

[in]

str

Another string to append.

Returns

Reference to this string.

GetLineEnd()

static const String& GetLineEnd ( )

static

Returns a string with the platform specific line ending.

Returns

String containing the line ending ("\r\n" or "\n").

operator->()

void operator-> ( ) const

private