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 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 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
 
Stringoperator+= (const String &str)
 

Static Public Member Functions

static const StringGetLineEnd ()
 

Private Member Functions

void operator-> () const
 

Member Typedef Documentation

◆ ValueType

◆ ConstIterator

◆ Iterator

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]strC string block.
[in]countNumber of characters, -1 to auto detect the length of the string (search for the first 0).
[in]stringDecodingEncoding 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]strC string block.
[in]stringDecodingEncoding 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]strChar block, for example a BaseArray<Char>.
[in]stringDecodingEncoding type.

◆ String() [4/10]

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

Constructor from CString.

Parameters
[in]strCString.
[in]stringDecodingEncoding 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]strUTF-32 character block.
[in]countNumber 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]strUTF-32 character block.

◆ String() [7/10]

String ( const Utf16Char str,
Int  count 
)
explicit

Constructor from UTF-16 Utf16Char array.

Parameters
[in]strUTF-16 character block.
[in]countNumber 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]countNumber of characters of the new string.
[in]fillCharCharacter 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]prefixThe prefix for the string.
[in]ptrA 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]prefixThe prefix string.
[in]ptrThe pointer that will be added as hexadecimal text.
[in]prefix0xIf 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]posPosition 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]positionPosition 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 ( void  ) 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]strAnother 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 "\r").

◆ operator->()

void operator-> ( ) const
private