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< IntGetCStringBlock (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< SysCharArrayGetSystemEncoding () 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< StringConvertString (const SCR &converter) const
 
MAXON_METHOD Result< StringPrettify (Int indent=0, const String &indentStr="\t"_s, Int breakUpThreshold=100, Bool angularBrackets=false) const
 
template<typename SCR >
Result< StringConvertString (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 StringInterfaceGetPart (StringPosition start, StringCount count) const
 
MAXON_METHOD StringInterfaceToUpper () const
 
MAXON_METHOD StringInterfaceToLower () 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< Float64ToFloat64 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< Float32ToFloat32 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< FloatToFloat (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< Int64ToInt64 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< Int32ToInt32 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< IntToInt (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< UInt64ToUInt64 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< UInt32ToUInt32 (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION Result< UIntToUInt (STRINGCONVERSION flags=STRINGCONVERSION::NONE) const
 
MAXON_FUNCTION StringInterfaceAppendInt (Int32 v)
 
MAXON_FUNCTION StringInterfaceAppendInt (Int64 v)
 
MAXON_FUNCTION StringInterfaceAppendUInt (UInt32 v)
 
MAXON_FUNCTION StringInterfaceAppendUInt (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< IntReplace (Utf32Char find, Utf32Char replace)
 
MAXON_METHOD Result< IntReplace (const String &find, const String &replace)
 
MAXON_METHOD Result< IntReplace (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 StringInterfaceGetLeftPart (StringPosition start) const
 
MAXON_FUNCTION StringInterfaceGetRightPart (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 StringGetAndCacheConstString (const wchar_t *chr, Int len)
 
static MAXON_METHOD const StringGetAndCacheConstString (const Char *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")
 

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"   
)
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]bufferBlock describing the buffer. A \0 byte will be appended to the string in any case.
[in]stringEncodingEncoding 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]arrayArray to be filled with the encoded string. The array is NOT terminated with a \0 byte.
[in]stringEncodingEncoding 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]stringEncodingEncoding 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]bufferPointer to the 8-bit character string.
[in]countNumber 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]stringDecodingDECODING 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]bufferBlock with an 8-bit character string.
[in]stringDecodingDECODING 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;
void * str
Definition: bytesobject.h:77
#define iferr_return
Definition: resultbase.h:1521
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]bufferPointer to the buffer with the string.
[in]countNumber 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]bufferPointer to the buffer with the string.
[in]countNumber 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]stringDataThe 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]bufferPointer to the buffer with the string.
[in]countNumber 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.

◆ 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]infoThe EnumInfo to use.
[in]valueThe enum value, converted to UInt64.
[in]formatStatementNullptr 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]converterString 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 = "\t"_s,
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]indentThe initial indent to use.
[in]indentStrThe indentation string to use, a tab character by default.
[in]breakUpThresholdThe maximum number of characters which shall be kept in a single line, 100 by default.
[in]angularBracketsWhen true, also angular brackets are handled. When false, only normal parentheses, curly and square brackets are considered.
Returns
The converted string.