#include <c4d_string.h>

Inheritance diagram for String:

Detailed Description

A String is a variable-length sequence of UTF-32 encoded Unicode characters. String provides methods and operators to simplify using character sequences.

Note: Cinema 4D strings are fully using UTF-32 Unicode characters. To avoid problems with Unicodes try to always use Utf32Char in your code unless you need to interface with the system or existing libraries.

Constructors/Destructors
	String ()

	String (const String &cs)=default

	String (String &&str)=default

	String (const maxon::String &cs)

	String (maxon::String &&str)

	String (const Utf16Char *s, Int count=-1)

	String (const Utf32Char *s, Int count=-1)

	String (const Char *cstr, const maxon::StringDecodingRef &stringDecoding=maxon::GetUtf8DefaultDecoder())

	String (const Char *cstr, STRINGENCODING type)

	String (Int count, Utf32Char fillch)

Operators
const String &	operator= (const String &str)

const String &	operator= (String &&str)

const String &	operator= (const maxon::String &str)

const String &	operator= (maxon::String &&str)

const String &	operator+= (const String &str)

String	operator+ (const String &str1, const String &str2)

String	operator+ (const String &str1, const Char *str2)

String	operator+ (const Char *str1, const String &str2)

Comparison
Int	CompareDeprecated (const String &cs) const

Int	LexCompare (const String &cs) const

Int	ComparePart (const String &str, Int cnt, Int pos) const

Int	LexComparePart (const String &str, Int cnt, Int pos) const

Find
Bool	FindFirst (const String &cs, Int32 *pos, Int start=0) const

Bool	FindLast (const String &cs, Int32 *pos, Int start=-1) const

Bool	FindFirst (Utf32Char ch, Int32 *pos, Int start=0) const

Bool	FindLast (Utf32Char ch, Int32 *pos, Int start=-1) const

Bool	FindFirstUpper (const String &findupper, Int32 *pos, Int start) const

Bool	FindLastUpper (const String &findupper, Int32 *pos, Int start) const

Delete/Insert/SubStr
void	Delete (Int pos, Int count)

void	InsertDeprecated (Int pos, Utf32Char ch)

void	InsertDeprecated (Int pos, const String &cs, Int start=-1, Int end=-1)

String	SubStr (Int start, Int count) const

String	Left (Int count) const

String	Right (Int count) const

Parse to Number
Float	ParseToFloat (Int32 *error=nullptr, Int unit=0, Int angletype=0, Int base=10) const

Int32	ParseToInt32 (Int32 *error=nullptr) const

Conversion to Number
Int32	ToInt32 (Bool *error) const

Int64	ToInt64 (Bool *error) const

UInt32	ToUInt32 (Bool *error) const

UInt64	ToUInt64 (Bool *error) const

Float	ToFloat (Bool *error) const

Int	ToInt (Bool *error) const

UInt	ToUInt (Bool *error) const

Conversion to Upper/Lower Case
String	ToUpper () const

String	ToLower () const

C and Unicode String Conversion
Int32	GetCStringLen (STRINGENCODING type=STRINGENCODING::XBIT) const

Int32	GetCString (Char *scstr, Int max, STRINGENCODING type=STRINGENCODING::XBIT) const

Char *	GetCStringCopy (STRINGENCODING type=STRINGENCODING::XBIT) const

void	SetCString (const Char *cstr, Int count=-1, STRINGENCODING type=STRINGENCODING::XBIT)

Conversion from Number
static String	MemoryToString (Int64 mem)

static String	HexToString (UInt32 v, Bool prefix0x=true)

static String	HexToString (UInt64 v, Bool prefix0x=true)

static String	IntToString (Int32 v)

static String	IntToString (Int64 v)

static String	UIntToString (UInt32 v)

static String	UIntToString (UInt64 v)

static String	FloatToString (Float32 v, Int32 vvk=-1, Int32 nnk=-3)

static String	FloatToString (Float64 v, Int32 vvk=-1, Int32 nnk=-3)

static String	FloatToStringDeprecated (Float32 v, Int32 vvk, Int32 nnk=-1, Bool e=false, Utf32Char xchar='0')

static String	FloatToStringDeprecated (Float64 v, Int32 vvk, Int32 nnk=-1, Bool e=false, Utf32Char xchar='0')

static String	VectorToString (const Vector32 &v, Int32 nnk=-1)

static String	VectorToString (const Vector64 &v, Int32 nnk=-1)

Additional Inherited Members
Public Types inherited from String
using	CharType = StringInterface::CharType

using	ValueType = Utf32Char

using	ConstIterator = StringIterator

using	Iterator = ConstIterator

Public Member Functions inherited from String
	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 inherited from String
static const String &	GetLineEnd ()

Constructor & Destructor Documentation

◆ String() [1/10]

String ( )

Default constructor.

◆ String() [2/10]

String ( const String & cs )

default

Copy constructor.

Parameters

[in] cs This String's characters are used to construct the String.

◆ String() [3/10]

String ( String && str )

default

◆ String() [4/10]

String ( const maxon::String & cs )

Copy constructor.

Parameters

[in] cs This String's characters are used to construct the String.

◆ String() [5/10]

String ( maxon::String && str )

Move constructor.

Parameters

[in] str This String's characters are used to construct the String.

◆ String() [6/10]

String	(	const Utf16Char *	s,
		Int	count = `-1`
	)

explicit

Constructs a string with the UTF-16 encoded Unicode characters in s.

Since: R17.032

Parameters

[in]	s	The Unicode character array to initialize the string from. The pointed array is copied.
[in]	count	The number of Utf16Char characters. If -1 is passed all characters will be copied until `'\0'` is found. Note that the string may have a different length than what you specify here as the UTF-16 encoding is transformed into a UTF-32 encoding.

◆ String() [7/10]

String	(	const Utf32Char *	s,
		Int	count = `-1`
	)

explicit

Constructs a string with the UTF-32 encoded Unicode characters in s.

Since: R17.032

Parameters

[in]	s	The Unicode character array to initialize the string from. The pointed array is copied.
[in]	count	The number of Utf32Char characters. If -1 is passed all characters will be copied until `'\0'` is found. Otherwise the resulting string length will match the given count.

◆ String() [8/10]

String	(	const Char *	cstr,
		const maxon::StringDecodingRef &	stringDecoding = `maxon::GetUtf8DefaultDecoder()`
	)

Constructs a String with the characters in cstr.

Note: If you have static strings use "..."_s instead.

Parameters

[in]	cstr	The character array in UTF8 encoding.
[in]	stringDecoding	Encoding type.

◆ String() [9/10]

String	(	const Char *	cstr,
		STRINGENCODING	type
	)

Constructs a String with the characters in cstr. Deprecated. Use the constructor with StringDecodingRef.

Parameters

[in]	cstr	The character array to initialize the string with. The passed data is decoded using type to UTF-32 internally.
[in]	type	The string encoding used to interpret cstr.

◆ String() [10/10]

String	(	Int	count,
		Utf32Char	fillch
	)

Constructs a string filled with the same character.

Parameters

[in]	count	The number of characters.
[in]	fillch	The fill character.

Member Function Documentation

◆ operator=() [1/4]

const String& operator= ( const String & str )

Assigns the characters from str.

Warning: The assignment operators makes string copies.

Parameters

[in] str The source string to assign.

Returns: The string that was set. Assigned to the left-hand operand.

◆ operator=() [2/4]

const String& operator= ( String && str )

◆ operator=() [3/4]

const String& operator= ( const maxon::String & str )

◆ operator=() [4/4]

const String& operator= ( maxon::String && str )

◆ operator+=()

const String& operator+= ( const String & str )

Concatenates the strings and sets the left-hand operand to the result.

Warning: The assignment operators makes string copies.

Parameters

[in] str The right-hand operand string.

Returns: The concatenated string. Assigned to the left-hand operand.

◆ CompareDeprecated()

Int CompareDeprecated ( const String & cs ) const

Compare the strings and returns their relationship. Deprecated. This is equivalent to maxon::String::Compare(cs, maxon::STRINGCOMPARISON::MEMORY).

Note: Comparison is case sensitive.

Parameters

[in] cs The string to compare against.

Returns: 0 if the strings are identical, < 0 if the string is less than cs, or > 0 if the string is greater than cs.

◆ LexCompare()

Int LexCompare ( const String & cs ) const

Compares the String object with another string and returns their relationship. Deprecated. This is equivalent to maxon::String::Compare(cs, maxon::STRINGCOMPARISON::CASEINSENSITIVE).

Parameters

[in] cs The string to compare against.

Returns: 0 if the strings are identical, < 0 if the string is less than cs, or > 0 if the string is greater than cs.

◆ ComparePart()

Int ComparePart	(	const String &	str,
		Int	cnt,
		Int	pos
	)		const

Compares a part of the string, specified by the position pos and the length cnt, with str.
Equivalent to (pos cnt. Compare(str). Deprecated. This is equivalent to maxon::String::ComparePart(str, maxon::STRINGCOMPARISON::MEMORY, pos, cnt).

Parameters

[in]	str	The string to compare against.
[in]	cnt	The number of characters of the part.
[in]	pos	The position of the part.

Returns: 0 if the strings are identical, < 0 if the string is less than str, or > 0 if the string is greater than str.

◆ LexComparePart()

Int LexComparePart	(	const String &	str,
		Int	cnt,
		Int	pos
	)		const

Compares a part of the string, specified by the position pos and the length cnt, with str and returns their relationship.
Equivalent to (pos cnt. LexCompare(str). Deprecated. This is equivalent to maxon::String::ComparePart(str, maxon::STRINGCOMPARISON::CASEINSENSITIVE, pos, cnt).

Parameters

[in]	str	The string to compare against.
[in]	cnt	The number of characters of the part.
[in]	pos	The position of the part.

Returns: 0 if the strings are identical, < 0 if the string is less than str, or > 0 if the string is greater than str.

◆ FindFirst() [1/2]

Bool FindFirst	(	const String &	cs,
		Int32 *	pos,
		Int	start = `0`
	)		const

Searches the string for the first match of the substring. Deprecated. This is equivalent to maxon::String::Find(cs, pos, start).

Parameters

[in]	cs	Substring to search for.
[out]	pos	A pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer.
[in]	start	The starting position in the string for the search: 0 <= start < GetLength().

Returns: true if the substring was found, otherwise false.

◆ FindLast() [1/2]

Bool FindLast	(	const String &	cs,
		Int32 *	pos,
		Int	start = `-1`
	)		const

Searches the string for the last match of the substring. Deprecated. This is equivalent to maxon::String::FindLast(cs, pos, start == -1 ? maxon::StringEnd() : maxon::StringPosition(start + 1)).

Parameters

[in]	cs	The substring to search for.
[out]	pos	A pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer.
[in]	start	The position to start from when searching backwards: 0 <= start < GetLength() or -1 for the end.

Returns: true if the substring was found, otherwise false.

◆ FindFirst() [2/2]

Bool FindFirst	(	Utf32Char	ch,
		Int32 *	pos,
		Int	start = `0`
	)		const

Searches the string for the first match of character ch. Deprecated. This is equivalent to maxon::String::FindFirst(ch, pos, start).

Parameters

[in]	ch	The character to find.
[out]	pos	A pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer.
[in]	start	The starting position in the string for the search: 0 <= start < GetLength().

Returns: true if the character was found, otherwise false.

◆ FindLast() [2/2]

Bool FindLast	(	Utf32Char	ch,
		Int32 *	pos,
		Int	start = `-1`
	)		const

Searches the string for the last match of character ch. Deprecated. This is equivalent to maxon::String::FindLast(ch, pos, start == -1 ? maxon::StringEnd() : maxon::StringPosition(start + 1)).

Parameters

[in]	ch	The character to find.
[out]	pos	A pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer.
[in]	start	The position to start from when searching backwards: 0 <= start < GetLength() or -1 for the end.

Returns: true if the character was found, otherwise false.

◆ FindFirstUpper()

Bool FindFirstUpper	(	const String &	findupper,
		Int32 *	pos,
		Int	start
	)		const

Searches the string for the first match of the upper-case substring. Deprecated. This is equivalent to maxon::String::FindUpper(findupper, pos, start).

Warning: findupper has to be uppercase.

Parameters

[in]	findupper	The upper-case substring to search for.
[out]	pos	A pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer.
[in]	start	The starting position in the string for the search: 0 <= start < GetLength().

Returns: true if the upper-case substring was found, otherwise false.

◆ FindLastUpper()

Bool FindLastUpper	(	const String &	findupper,
		Int32 *	pos,
		Int	start
	)		const

Searches the string for the last match of the upper-case substring. Deprecated. This is equivalent to maxon::String::FindLastUpper(findupper, pos, start == -1 ? maxon::StringEnd() : maxon::StringPosition(start + 1))

Warning: findupper has to be uppercase.

Parameters

[in]	findupper	The upper-case substring to search for.
[out]	pos	A pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer.
[in]	start	The position to start from when searching backwards: 0 <= start < GetLength() or -1 for the end.

Returns: true if the upper-case substring was found, otherwise false.

◆ Delete()

void Delete	(	Int	pos,
		Int	count
	)

Removes a section from the string. Deprecated. This is equivalent to maxon::String::Erase(pos, count).

Parameters

[in]	pos	The starting position to remove: 0 <= pos < GetLength().
[in]	count	The number of characters to remove: 0 <= count < GetLength()-pos.

◆ InsertDeprecated() [1/2]

void InsertDeprecated	(	Int	pos,
		Utf32Char	ch
	)

Inserts a character into the string. Deprecated. This is equivalent to maxon::String::Insert(pos, ch).

Parameters

[in]	pos	The position to insert the character: 0 <= pos < GetLength().
[in]	ch	The character to insert.

◆ InsertDeprecated() [2/2]

void InsertDeprecated	(	Int	pos,
		const String &	cs,
		Int	start = `-1`,
		Int	end = `-1`
	)

Inserts another string into the string. Deprecated. This is equivalent to maxon::String::Insert(pos, cs, start == -1 ? 0 : start, end == -1 ? maxon::StringEnd() : maxon::StringPosition(end)).

Parameters

[in]	pos	The position to insert the string: 0 <= pos < GetLength().
[in]	cs	The string to insert.
[in]	start	The start position within the inserted string to only insert parts of the string.
[in]	end	End position within the inserted string to only insert parts of the string.

◆ SubStr()

String SubStr	(	Int	start,
		Int	count
	)		const

Extracts a substring from the string. Deprecated. This is equivalent to maxon::String::GetPart(a, b).

Parameters

[in]	start	The position to extract the substring from. Must be 0 <= pos < GetLength().
[in]	count	The number of characters of the substring: 0 <= count < GetLength()-start

Returns: The substring.

◆ Left()

String Left ( Int count ) const

Extracts a substring from the left of the string. Deprecated. This is equivalent to maxon::String::GetPart(-count, maxon::StringEnd()).

Parameters

[in] count The number of characters of the substring: 0 <= count < GetLength()

Returns: The substring.

◆ Right()

String Right ( Int count ) const

Extracts a substring from the right of the string. Deprecated. This is equivalent to maxon::String::GetPart(-count, maxon::StringEnd()).

Parameters

[in] count The number of characters of the substring: 0 <= count < GetLength()

Returns: The substring.

◆ ParseToFloat()

Float ParseToFloat	(	Int32 *	error = `nullptr`,
		Int	unit = `0`,
		Int	angletype = `0`,
		Int	base = `10`
	)		const

Converts the string into a Float value.

Parameters

[in]	error	A pointer to an Int32 to report any errors of conversion. The caller owns the pointed variable. The function succeeded if error==0.
[in]	unit	The unit type: UNIT
[in]	angletype	The angle type: ANGLE
[in]	base	The base of the number system used in the string.

Returns: The Float value represented by the string.

◆ ParseToInt32()

Int32 ParseToInt32 ( Int32 * error = nullptr ) const

Converts the string into an Int32 value. Deprecated. This is equivalent to maxon::String::ToInt32().

Parameters

[in] error A pointer to an Int32 to report any errors of conversion. The caller owns the pointed variable.
The function succeeded if error==0.

Returns: The Int32 value represented by the string.

◆ MemoryToString()

static String MemoryToString ( Int64 mem )

static

Converts a Int64 into a memory size formated (B,KB,MB) string. Deprecated. This is equivalent to maxon::String::MemorySizeToString(v, true).

Parameters

[in] mem The Int64 memory value to convert.

Returns: The Int64 memory as a string.

◆ HexToString() [1/2]

static String HexToString	(	UInt32	v,
		Bool	prefix0x = `true`
	)

static

Converts a UInt32 hexadecimal value into a string (usually used with pointers). Deprecated. This is equivalent to maxon::String::HexToString(v, prefix0x).

Parameters

[in]	v	The hexadecimal value to convert.
[in]	prefix0x	Set to false to disable '0x' prefix in the returned string.

Returns: The hexadecimal value as a string.

◆ HexToString() [2/2]

static String HexToString	(	UInt64	v,
		Bool	prefix0x = `true`
	)

static

Converts a UInt64 hexadecimal value into a string (usually used with pointers). Deprecated. This is equivalent to maxon::String::HexToString(v, prefix0x).

Parameters

[in]	v	The hexadecimal value to convert.
[in]	prefix0x	Set to false to disable '0x' prefix in the returned string.

Returns: The hexadecimal value as a string.

◆ IntToString() [1/2]

static String IntToString ( Int32 v )

static

Converts an Int32 to a String. Deprecated. This is equivalent to maxon::String::IntToString(v).

Parameters

[in] v Int32 value.

Returns: String object with the decimal text of the value. Will be an empty reference on failure (apply iferr for error handling).

◆ IntToString() [2/2]

static String IntToString ( Int64 v )

static

Converts an Int64 to a String. Deprecated. This is equivalent to maxon::String::IntToString(v).

Parameters

[in] v Int64 value.

Returns: String object with the decimal text of the value. Will be an empty reference on failure (apply iferr for error handling).

◆ UIntToString() [1/2]

static String UIntToString ( UInt32 v )

static

Converts an UInt32 to a String. Deprecated. This is equivalent to maxon::String::UIntToString(v).

Parameters

[in] v UInt32 value.

Returns: String object with the decimal text of the value. Will be an empty reference on failure (apply iferr for error handling).

◆ UIntToString() [2/2]

static String UIntToString ( UInt64 v )

static

Converts an UInt64 to a String. Deprecated. This is equivalent to maxon::String::UIntToString(v).

Parameters

[in] v UInt64 value.

Returns: String object with the decimal text of the value. Will be an empty reference on failure (apply iferr for error handling).

◆ FloatToString() [1/2]

static String FloatToString	(	Float32	v,
		Int32	vvk = `-1`,
		Int32	nnk = `-3`
	)

static

Converts a Float32 into a String. Deprecated. This is equivalent to maxon::String::FloatToString(v, ...).

Parameters

[in]	v	The Float32 value to convert.
[in]	vvk	The number of digits in front of the comma.
[in]	nnk	The number of digits after the comma.

Returns: The Float32 as a string.

◆ FloatToString() [2/2]

static String FloatToString	(	Float64	v,
		Int32	vvk = `-1`,
		Int32	nnk = `-3`
	)

static

Converts a Float64 into a String. Deprecated. This is equivalent to maxon::String::FloatToString(v, ...).

Parameters

[in]	v	The Float64 value to convert.
[in]	vvk	The number of digits in front of the comma.
[in]	nnk	The number of digits after the comma.

Returns: The Float64 as a string.

◆ FloatToStringDeprecated() [1/2]

static String FloatToStringDeprecated	(	Float32	v,
		Int32	vvk,
		Int32	nnk = `-1`,
		Bool	e = `false`,
		Utf32Char	xchar = `'0'`
	)

static

Converts a Float32 into a String. Deprecated. This is equivalent to maxon::String::FloatToString(v, ...).

Parameters

[in]	v	The Float32 value to convert.
[in]	vvk	The number of digits in front of the comma. (-1)
[in]	nnk	The number of digits after the comma.
[in]	e	Set to true to use exponential writing.
[in]	xchar	The leading chars will be filled with this character. e.g. the value 100 with vvk==5 will looks like this: 00100.

Returns: The Float32 as a string.

◆ FloatToStringDeprecated() [2/2]

static String FloatToStringDeprecated	(	Float64	v,
		Int32	vvk,
		Int32	nnk = `-1`,
		Bool	e = `false`,
		Utf32Char	xchar = `'0'`
	)

static

Converts a Float64 into a String. Deprecated. This is equivalent to maxon::String::FloatToString(v, ...).

Parameters

[in]	v	The Float64 value to convert.
[in]	vvk	The number of digits in front of the comma (-1).
[in]	nnk	The number of digits after the comma.
[in]	e	Set to true to use exponential writing.
[in]	xchar	The leading chars will be filled with this character. e.g. the value 100 with vvk==5 will looks like this: 00100.

Returns: The Float64 as a string.

◆ VectorToString() [1/2]

static String VectorToString	(	const Vector32 &	v,
		Int32	nnk = `-1`
	)

static

Converts a Vector32 into a String.

Parameters

[in]	v	The Vector32 value to convert.
[in]	nnk	The number of digits after the comma.

Returns: The Vector32 as a string.

◆ VectorToString() [2/2]

static String VectorToString	(	const Vector64 &	v,
		Int32	nnk = `-1`
	)

static

Converts a Vector64 into a String.

Parameters

[in]	v	The Vector64 value to convert.
[in]	nnk	The number of digits after the comma.

Returns: The Vector64 as a string.