StringInterface Class Reference

#include <string.h>

Inheritance diagram for StringInterface:

Detailed Description

Class to store unicode strings. String stores 16bit unicode characters. Any 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.

@MAXON_ANNOTATION{refclass=false}

Public Member Functions
MAXON_METHOD Result< Int >	GetCStringBlock (const Block< Char > &buffer, const StringEncodingRef &stringEncoding=GetUtf8DefaultEncoder()) const
MAXON_METHOD Result< void >	GetCStringAppendArray (const NonConstArray< Char > &array, const StringEncodingRef &stringEncoding=GetUtf8DefaultEncoder()) const
MAXON_METHOD Result< BaseArray< Char > >	GetCString (const StringEncodingRef &stringEncoding=GetUtf8DefaultEncoder()) const
MAXON_METHOD Result< void >	SetCString (const Char *buffer, Int count=-1, const StringDecodingRef &stringDecoding=GetUtf8DefaultDecoder())
MAXON_FUNCTION Result< void >	SetCString (const Block< const Char > &buffer, const StringDecodingRef &stringDecoding=GetUtf8DefaultDecoder())
MAXON_METHOD Result< SysCharArray >	GetSystemEncoding () const
MAXON_METHOD Result< void >	SetSystemEncoding (const SysChar *buffer, Int count=-1)
MAXON_METHOD Result< void >	SetUtf32 (const Utf32Char *buffer, Int count=-1)
MAXON_METHOD Result< void >	GetUtf16 (Utf16CharBuffer &stringData) const
MAXON_METHOD Result< void >	SetUtf16 (const Utf16Char *buffer, Int count=-1)
String	ToString (const FormatStatement *formatStatement=nullptr) const
MAXON_METHOD StridedBlock< const Generic >	GetVariableInternalData () const
MAXON_METHOD Int	GetCharacterWidth () const
template<typename SCR = StreamConversionRef>
MAXON_FUNCTION Result< String >	ConvertString (const SCR &converter) const
MAXON_METHOD Result< String >	Prettify (Int indent=0, const String &indentStr=CONSTSTRING("\t"), Int breakUpThreshold=100, Bool angularBrackets=false) const
template<typename SCR >
Result< String >	ConvertString (const SCR &converter) const
Public Member Functions inherited from StringTemplate< StringInterface, String, Utf32Char >
MAXON_METHOD Int	GetLength () const
MAXON_METHOD Result< void >	Init (Int count=0, Utf32Char fillChar=0)
MAXON_METHOD Result< void >	Shrink ()
MAXON_METHOD Result< void >	Append (const StringInterface *str)
MAXON_FUNCTION Result< void >	Append (const String &str)
MAXON_METHOD Result< void >	Append (const Utf32Char *str, Int len)
MAXON_FUNCTION Result< void >	Append (const Block< const Utf32Char > &block)
MAXON_FUNCTION Result< void >	AppendChar (Utf32Char v)
MAXON_METHOD Int	FindIndex (const StringInterface *str, StringPosition start=0) const
MAXON_METHOD Int	FindIndex (Utf32Char ch, StringPosition start=0) const
MAXON_METHOD Int	FindLastIndex (const StringInterface *str, StringPosition start=StringEnd()) const
MAXON_METHOD Int	FindLastIndex (Utf32Char ch, StringPosition start=StringEnd()) const
MAXON_METHOD Int	FindUpperIndex (const StringInterface *str, StringPosition start=0) const
MAXON_METHOD Int	FindLastUpperIndex (const StringInterface *str, StringPosition start=StringEnd()) const
MAXON_METHOD Result< void >	Erase (StringPosition position, StringCount count)
MAXON_METHOD Result< void >	Insert (StringPosition position, const StringInterface *str, StringPosition strStart=0, StringCount strCount=StringEnd())
MAXON_METHOD Result< void >	Insert (StringPosition position, Utf32Char ch)
MAXON_METHOD StringInterface *	GetPart (StringPosition start, StringCount count) const
MAXON_METHOD StringInterface *	ToUpper () const
MAXON_METHOD StringInterface *	ToLower () const
MAXON_METHOD COMPARERESULT	ComparePart (const StringInterface *str, STRINGCOMPARISON mode, StringPosition position, StringCount count) const
MAXON_FUNCTION COMPARERESULT	Compare (const StringInterface *str, STRINGCOMPARISON mode=STRINGCOMPARISON::UNICODE_NUMBERS) const
MAXON_FUNCTION Bool	IsEqual (const StringInterface *str) const
MAXON_METHOD HashInt	GetHashCode () const
MAXON_METHOD UniqueHash	GetUniqueHashCode () const
MAXON_METHOD void	SetChar (Int pos, Utf32Char ch)
MAXON_METHOD Utf32Char	GetChar (Int pos) const
MAXON_FUNCTION Result< Float64 >	ToFloat64 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< Float32 >	ToFloat32 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< Float >	ToFloat (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< Int64 >	ToInt64 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< Int32 >	ToInt32 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< Int >	ToInt (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< UInt64 >	ToUInt64 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< UInt32 >	ToUInt32 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION Result< UInt >	ToUInt (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
MAXON_FUNCTION StringInterface *	AppendInt (Int32 v)
MAXON_FUNCTION StringInterface *	AppendInt (Int64 v)
MAXON_FUNCTION StringInterface *	AppendUInt (UInt32 v)
MAXON_FUNCTION StringInterface *	AppendUInt (UInt64 v)
MAXON_METHOD Result< void >	GetUtf32 (Utf32CharBuffer &stringData) const
MAXON_METHOD Result< void >	TrimLeft ()
MAXON_METHOD Result< void >	TrimRight ()
MAXON_METHOD Result< void >	Split (const String &splitSymbol, Bool trim, const ValueReceiver< const String & > &parts) const
MAXON_METHOD Result< Int >	Replace (Utf32Char find, Utf32Char replace)
MAXON_METHOD Result< Int >	Replace (const String &find, const String &replace)
MAXON_METHOD Result< Int >	Replace (Utf32Char find, const String &replace)
MAXON_FUNCTION Bool	Find (const String &str, Int *pos, StringPosition start=0) const
MAXON_FUNCTION Bool	Find (Utf32Char ch, Int *pos, StringPosition start=0) const
MAXON_FUNCTION Bool	FindLast (const String &str, Int *pos, StringPosition start=StringEnd()) const
MAXON_FUNCTION Bool	FindLast (Utf32Char ch, Int *pos, StringPosition start=StringEnd()) const
MAXON_FUNCTION Bool	FindUpper (const String &str, Int *pos, StringPosition start=0) const
MAXON_FUNCTION Bool	FindLastUpper (const String &str, Int *pos, StringPosition start=StringEnd()) const
MAXON_FUNCTION StringInterface *	GetLeftPart (StringPosition start) const
MAXON_FUNCTION StringInterface *	GetRightPart (StringPosition start) const
MAXON_FUNCTION Bool	StartsWith (Utf32Char ch) const
MAXON_FUNCTION Bool	StartsWith (const String &str) const
MAXON_FUNCTION Bool	EndsWith (Utf32Char ch) const
MAXON_FUNCTION Bool	EndsWith (const String &str) const
MAXON_FUNCTION Result< void >	Trim ()

Static Public Member Functions
static MAXON_METHOD const String &	GetAndCacheConstString (const wchar_t *chr, Int len)
static MAXON_METHOD const String &	GetAndCacheConstString (const Char *chr, Int len, Int isUtf8)
template<typename T >
static MAXON_ATTRIBUTE_FORCE_INLINE const String &	GetAndCacheConstStringT (const T *chr, Int len, Int isUtf8)
static MAXON_METHOD String	PrivateEnumToString (const EnumInfo &info, UInt64 value, const FormatStatement *formatStatement)
Static Public Member Functions inherited from StringTemplate< StringInterface, String, Utf32Char >
static MAXON_FUNCTION String	FloatToString (Float32 value, Int charsBeforeComma=STRING_DYNAMIC_DIGITS, Int digitsAfterComma=-3, Bool exponent=false, Utf32Char fillChar=' ')
static MAXON_FUNCTION String	FloatToString (Float64 value, Int charsBeforeComma=STRING_DYNAMIC_DIGITS, Int digitsAfterComma=-3, Bool exponent=false, Utf32Char fillChar=' ')
static MAXON_FUNCTION String	IntToString (Int32 v)
static MAXON_FUNCTION String	IntToString (Int64 v)
static MAXON_FUNCTION String	UIntToString (UInt32 v)
static MAXON_FUNCTION String	UIntToString (UInt64 v)
static MAXON_FUNCTION String	MemorySizeToString (Int64 v, Bool mebibytes=true)
static MAXON_FUNCTION String	HexToString (UInt32 v, Bool prefix0x=true)
static MAXON_FUNCTION String	HexToString (UInt64 v, Bool prefix0x=true)
static MAXON_FUNCTION String	PointerToString (const void *v)

Private Member Functions
	MAXON_INTERFACE_NONVIRTUAL (StringInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxon.interface.string", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))

Additional Inherited Members
Public Types inherited from StringTemplate< StringInterface, String, Utf32Char >
using	Super = StringTemplate
using	CharType = Utf32Char

Member Function Documentation

MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( StringInterface  , MAXON_REFERENCE_COPY_ON_WRITE  , "net.maxon.interface.string"  , MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")    )

private

GetCStringBlock()

MAXON_METHOD Result<Int> GetCStringBlock	(	const Block< Char > &	buffer,
		const StringEncodingRef &	stringEncoding = GetUtf8DefaultEncoder()
	)		const

Converts a unicode string to a 8-bit encoded character string and copies it into buffer. The buffer size is taken into account.

Parameters

[in,out]	buffer	Block describing the buffer. A \0 byte will be appended to the string in any case.
[in]	stringEncoding	Encoding for the string. By default UTF-8 is selected. If a nullptr is passed the data is truncated to Char and no conversion takes place.

Returns

The length of the corresponding 8-bit string for the given encoding. The \0 byte is excluded.

GetCStringAppendArray()

MAXON_METHOD Result<void> GetCStringAppendArray	(	const NonConstArray< Char > &	array,
		const StringEncodingRef &	stringEncoding = GetUtf8DefaultEncoder()
	)		const

Converts a unicode string to a 8-bit encoded character string and appends it to the given array.

Parameters

[in,out]	array	Array to be filled with the encoded string. The array is NOT terminated with a \0 byte.
[in]	stringEncoding	Encoding for the string. By default UTF-8 is selected. If a nullptr is passed the data is truncated to Char and no conversion takes place.

Returns

OK on success.

GetCString()

MAXON_METHOD Result<BaseArray<Char> > GetCString

(

const StringEncodingRef &

stringEncoding = GetUtf8DefaultEncoder()

)

const

Converts a unicode string to a 8-bit encoded character string and returns a new BaseArray<>.

Parameters

[in]

stringEncoding

Encoding for the string. By default UTF-8 is selected. If a nullptr is passed the data is truncated to Char and no conversion takes place.

Returns

BaseArray<Char> with the encoded string. The string is \0 - terminated, but the array size is equal to the string length without the \0 character.

SetCString() [1/2]

MAXON_METHOD Result<void> SetCString	(	const Char *	buffer,
		Int	count = -1,
		const StringDecodingRef &	stringDecoding = GetUtf8DefaultDecoder()
	)

Initializes the string with a given 8-bit Char string with the given encoding.

Parameters

[out]	buffer	Pointer to the 8-bit character string.
[in]	count	Number of valid characters in the buffer, a value of -1 automatically detects the string length by searching for the first \0 character, otherwise count is relevant and not \0.
[in]	stringDecoding	DECODING for the string. By default UTF-8 is selected. If a nullptr is passed the data is copied 1:1.

Returns

OK on success.

SetCString() [2/2]

MAXON_FUNCTION Result<void> SetCString	(	const Block< const Char > &	buffer,
		const StringDecodingRef &	stringDecoding = GetUtf8DefaultDecoder()
	)

Initializes the string with a given 8-bit Char string with the given encoding.

Parameters

[out]	buffer	Block with an 8-bit character string.
[in]	stringDecoding	DECODING for the string. By default UTF-8 is selected. If a nullptr is passed the data is copied 1:1.

Returns

OK on success.

GetSystemEncoding()

MAXON_METHOD Result<SysCharArray> GetSystemEncoding

(

)

const

Returns a copy of the string as a system-specific character array. The string will be \0 - terminated. GetFirst() on that call always return a valid pointer, even if the string length is 0! GetLength() returns the real string length without the trailing \0.

SysCharArray converted = str.GetSystemEncoding() iferr_return;

Returns

A copy of the character string.

SetSystemEncoding()

MAXON_METHOD Result<void> SetSystemEncoding	(	const SysChar *	buffer,
		Int	count = -1
	)

Initializes the String with the given system-specific character string.

Parameters

[in]	buffer	Pointer to the buffer with the string.
[in]	count	Number of valid characters in the buffer. A count of -1 calculates the string length automatically, terminating when \0 is found.

Returns

OK on success.

SetUtf32()

MAXON_METHOD Result<void> SetUtf32	(	const Utf32Char *	buffer,
		Int	count = -1
	)

Initializes the String with the given 32-bit unicode character string.

Parameters

[in]	buffer	Pointer to the buffer with the string.
[in]	count	Number of valid characters in the buffer. A count of -1 calculates the string length automatically, terminating when \0 is found.

Returns

OK on success.

GetUtf16()

MAXON_METHOD Result<void> GetUtf16

(

Utf16CharBuffer &

stringData

)

const

Copies the string as UTF-16 encoded characters into the passed array. The array will be resized and contain the non \0 - terminated data.

Parameters

[out]

stringData

The array to receive the data.

Returns

OK on success.

SetUtf16()

MAXON_METHOD Result<void> SetUtf16	(	const Utf16Char *	buffer,
		Int	count = -1
	)

Initializes the String with the given 16-bit unicode character string.

Parameters

[in]	buffer	Pointer to the buffer with the string.
[in]	count	Number of valid characters in the buffer. A count of -1 calculates the string length automatically, terminating when \0 is found.

Returns

OK on success.

GetAndCacheConstString() [1/2]

static MAXON_METHOD const String& GetAndCacheConstString ( const wchar_t *  chr, Int  len  )

static

Internal. Caches a static constant string and returns a maxon::String.

GetAndCacheConstString() [2/2]

static MAXON_METHOD const String& GetAndCacheConstString ( const Char *  chr, Int  len, Int  isUtf8  )

static

Internal. Caches a static constant string and returns a maxon::String.

GetAndCacheConstStringT()

static MAXON_ATTRIBUTE_FORCE_INLINE const String& GetAndCacheConstStringT ( const T *  chr, Int  len, Int  isUtf8  )

static

PrivateEnumToString()

static MAXON_METHOD String PrivateEnumToString ( const EnumInfo &  info, UInt64  value, const FormatStatement *  formatStatement  )

static

Internal. Converts the given enum value to a string.

Parameters

[in]	info	The EnumInfo to use.
[in]	value	The enum value, converted to UInt64.
[in]	formatStatement	Nullptr or additional formatting instruction. Currently no additional formatting instructions are supported.

GetVariableInternalData()

MAXON_METHOD StridedBlock<const Generic> GetVariableInternalData

(

)

const

Returns the internal character array. Temporarily renamed.

Returns

Block describing the internal character buffer. The data is read only! Please note that GetCount() will return the number of characters (and not bytes).

GetCharacterWidth()

MAXON_METHOD Int GetCharacterWidth

(

)

const

Retrieves the string's character width. The width determines the result of GetInternalDataX().

Returns

1, 2 or 4 (bytes).

ConvertString()

MAXON_FUNCTION Result<String> ConvertString

(

const SCR &

converter

)

const

Converts a string using a UTF32 -> UTF32 encoder or decoder (e.g. StringEncodings::Url32).

Parameters

[in]

converter

String encoder or decoder that should be applied to the conversion.

Returns

The converted string.

Prettify()

MAXON_METHOD Result<String> Prettify	(	Int	indent = 0,
		const String &	indentStr = CONSTSTRING("\t"),
		Int	breakUpThreshold = 100,
		Bool	angularBrackets = false
	)		const

Returns a "prettified" version of this string where line breaks and indentations are added according to parentheses and commas.

Parameters

[in]	indent	The initial indent to use.
[in]	indentStr	The indentation string to use, a tab character by default.
[in]	breakUpThreshold	The maximum number of characters which shall be kept in a single line, 100 by default.
[in]	angularBrackets	When true, also angular brackets are handled. When false, only normal parentheses, curly and square brackets are considered.

Returns

The converted string.