#include <c4d_string.h>

Classes
class	PChar

Public Member Functions
Int32	GetLength () const

Bool	IsPopulated () const

void	Init (Int32 count=0, UInt16 fillChar=0)

void	ShrinkToLen ()

Protected Member Functions
void	IncSize (Int32 nSize)

Private Attributes
Int32	Size

Int32	Len

UInt16 *	Txt

void *	future_enhancements

Friends
class	String::PChar

Constructors/Destructors
	String ()

	String (const String &str)

	String (const Char *cStr, STRINGENCODING type=STRINGENCODING_XBIT)

	String (const UInt16 *uStr)

	String (const UInt16 *uStr, Int32 count)

	String (Int32 count, UInt16 fillChar)

	~String ()

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

const String &	operator= (const String &str)

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

Bool	operator< (const String &str) const

Bool	operator> (const String &str) const

Bool	operator<= (const String &str) const

Bool	operator>= (const String &str) const

Bool	operator== (const String &str) const

Bool	operator!= (const String &str) const

Comparison
Int32	Compare (const String &str) const

Int32	ComparePart (const String &str, Int32 count, Int32 pos) const

Int32	LexCompare (const String &str) const

Int32	RelCompare (const String &str) const

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

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

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

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

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

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

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

void	Insert (Int32 pos, const String &str, Int32 start=-1, Int32 end=-1)

void	Insert (Int32 pos, UInt16 ch)

const String	SubStr (Int32 start, Int32 count) const

String	Left (Int count) const

String	Right (Int count) const

Parse to Number
Int32	ParseToInt32 (Int32 *error=nullptr) const

Conversion from Number
static String	FloatToString (Float v, Int32 vvk=-1, Int32 nnk=-1, Bool e=false, UInt16 xchar='0')

static String	IntToString (Int32 v)

static String	UIntToString (UInt32 v)

static String	IntToString (Int64 v)

static String	UIntToString (UInt64 v)

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

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

Convert to Upper/Lower Case
const String	ToUpper () const

const String	ToLower () const

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

Int32	GetCString (Char *cStr, Int32 max, STRINGENCODING type=STRINGENCODING_XBIT) const

Int32	SetCString (const Char *cStr, Int32 count=-1, STRINGENCODING type=STRINGENCODING_XBIT)

Char *	GetCStringCopy (STRINGENCODING type=STRINGENCODING_XBIT) const

void	GetUcBlockNull (UInt16 *ubc, Int32 max) const

UInt16 *	GetUcBlockNullCopy () const

void	GetUcBlock (UInt16 *ubc, Int32 max) const

void	SetUcBlock (const UInt16 *ubc, Int32 count)

Int32	GetDataPtr (const UInt16 **outPtr) const

const PChar	operator[] (Int32 pos) const

PChar	operator[] (Int32 pos)

Detailed Description

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

Note: Cinema 4D strings are fully using Unicode characters.

Constructor & Destructor Documentation

◆ String() [1/6]

String ( )

Default constructor.

◆ String() [2/6]

String ( const String & str )

Copy constructor.

Parameters

[in] str The characters used to construct the String.

◆ String() [3/6]

String	(	const Char *	cStr,
		STRINGENCODING	type = `STRINGENCODING_XBIT`
	)

Constructs the String with the characters in Cstr.

Parameters

[in]	cStr	The character array to initialize the string from. Must be formatted using the STRINGENCODING_XBIT scheme. The pointed array is copied.
[in]	type	The string encoding.

◆ String() [4/6]

String ( const UInt16 * uStr )

Constructs the string with the Unicode characters in Ustr.

Parameters

[in] uStr The Unicode character array to initialize the string from. The pointed array is copied.

◆ String() [5/6]

String	(	const UInt16 *	uStr,
		Int32	count
	)

Constructs the string with the Unicode characters in Ustr.

Parameters

[in]	uStr	The Unicode character array to initialize the string from. The pointed array is copied.
[in]	count	The length of Ustr string.

◆ String() [6/6]

String	(	Int32	count,
		UInt16	fillChar
	)

Constructs a string filled with the same character.

Parameters

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

◆ ~String()

~String ( )

Default destructor.

Member Function Documentation

◆ IncSize()

void IncSize ( Int32 nSize )

protected

Private. Internal.

◆ GetLength()

Int32 GetLength ( ) const

Gets the number of characters in the string.

Returns: The number of characters in the string.

◆ IsPopulated()

Bool IsPopulated ( ) const

Checks if the string has any characters in it.

Since: R20 Was Content() before.

Returns: true if the string is not empty, otherwise false.

◆ Init()

void Init	(	Int32	count = `0`,
		UInt16	fillChar = `0`
	)

Initializes the string.

Parameters

[in]	count	The length of the string.
[in]	fillChar	The fill character.

◆ ShrinkToLen()

void ShrinkToLen ( )

Resizes the string according to its length. Optimizes the memory usage after delete, initialize etc.

◆ operator=()

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+=()

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

Concatenates the strings and set 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.

◆ operator<()

Bool operator< ( const String & str ) const

Compares the strings to see if the the left-hand string is less than the right-hand string.

Note: The comparison is done alphanumerically and case-sensitive.

Parameters

[in] str The right-hand operand string.

Returns: The result of the comparison.

◆ operator>()

Bool operator> ( const String & str ) const

Compares the strings to see if the the left-hand string is greater than the right-hand string.

Note: The comparison is done alphanumerically and case-sensitive.

Parameters

[in] str The right-hand operand string.

Returns: The result of the comparison.

◆ operator<=()

Bool operator<= ( const String & str ) const

Compares the strings to see if the the left-hand string is less than or the same as right-hand string.

Note: The comparison is done alphanumerically and case-sensitive.

Parameters

[in] str The right-hand operand string.

Returns: The result of the comparison.

◆ operator>=()

Bool operator>= ( const String & str ) const

Compares the strings to see if the left-hand string is greater than or the same as the right-hand string.

Note: The comparison is done alphanumerically and case-sensitive.

Parameters

[in] str The right-hand operand string.

Returns: The result of the comparison.

◆ operator==()

Bool operator== ( const String & str ) const

Check if strings are equal.

Note: The comparison is done alphanumerically and case-sensitive.

Parameters

[in] str The right-hand operand string.

Returns: true if strings are equal, otherwise false.

◆ operator!=()

Bool operator!= ( const String & str ) const

Checks if strings are different.

Note: The comparison is done alphanumerically and case-sensitive.

Parameters

[in] str The right-hand operand string.

Returns: true if strings are different, otherwise false.

◆ Compare()

Int32 Compare ( const String & str ) const

Compares the string with another string and returns their relationship.

Note: Comparison is case sensitive.

Parameters

[in] str The string to compare against.

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

◆ ComparePart()

Int32 ComparePart	(	const String &	str,
		Int32	count,
		Int32	pos
	)		const

Compares part of the string, specified by the position pos and the length cnt, with str. Equivalent to SubStr(pos, cnt).Compare(str).

Parameters

[in]	str	The string to compare against.
[in]	count	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.

◆ LexCompare()

Int32 LexCompare ( const String & str ) const

Compares the String object with another string and returns their relationship, this is case insensitive.

Note: Comparison is case insensitive. Special characters (ASCII value >= 128) are not handled case-insensitive (like 'Ö', 'ä', 'ß').

Parameters

[in] str The string to compare against.

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

◆ RelCompare()

Int32 RelCompare ( const String & str ) const

Incremental compare: the bigger the absolute return value, the bigger the difference.

Parameters

[in] str The string to compare against.

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 &	str,
		Int32 *	pos,
		Int32	start = `0`
	)		const

Searches the string for the first match of the substring.

Parameters

[in]	str	Substring to search for.
[in]	pos	Pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]	start	Starting position in the string for the search. Must be 0 <= Start < GetLength().

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

◆ FindLast() [1/2]

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

Searches the string for the last match of the substring.

Parameters

[in]	str	Substring to search for.
[in]	pos	Pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]	start	Position to start from when searching backwards,-1 means at the end. Must be 0 <= Start < GetLength() or -1 for the end.

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

◆ FindFirst() [2/2]

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

Searches the string for the first match of character ch.

Parameters

[in]	ch	The character to find.
[in]	pos	Pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]	start	Starting position in the string for the search. Must be 0 <= Start < GetLength().

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

◆ FindLast() [2/2]

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

Search the string for the last match of character ch.

Parameters

[in]	ch	The character to find.
[in]	pos	Pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]	start	Position to start from when searching backwards,-1 means at the end. Must be 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,
		Int32	start
	)		const

Searches the string for the first match of the upper-case substring.

Parameters

[in]	findUpper	Upper-case substring to search for.
[in]	pos	Pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]	start	Starting position in the string for the search. Must be 0 <= Start < GetLength().

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

◆ FindLastUpper()

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

Searches the string for the last match of the upper-case substring.

Parameters

[in]	findUpper	Upper-case substring to search for.
[in]	pos	Pointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]	start	Position to start from when searching backwards,-1 means at the end. Must be 0 <= Start < GetLength() or -1 for the end.

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

◆ Delete()

void Delete	(	Int32	pos,
		Int32	count
	)

Removes a section from the string.

Parameters

[in]	pos	Starting position to remove. Must be 0 <= Pos < GetLength().
[in]	count	Number of characters to remove. Must be 0 <= Count < GetLength()-Pos.

◆ Insert() [1/2]

void Insert	(	Int32	pos,
		const String &	str,
		Int32	start = `-1`,
		Int32	end = `-1`
	)

Inserts another string into the string.

Parameters

[in]	pos	Position to insert the string. Must be 0 <= Pos < GetLength().
[in]	str	String to insert.
[in]	start	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.

◆ Insert() [2/2]

void Insert	(	Int32	pos,
		UInt16	ch
	)

Inserts a character into the string.

Parameters

[in]	pos	Position to insert the character. Must be 0 <= Pos < GetLength().
[in]	ch	Character to insert.

◆ SubStr()

const String SubStr	(	Int32	start,
		Int32	count
	)		const

Extracts a substring from the String.

Parameters

[in]	start	Position to extract the substring from. Must be 0 <= Pos < GetLength().
[in]	count	Number of characters of the substring. Must be 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.

◆ ParseToInt32()

Int32 ParseToInt32 ( Int32 * error = nullptr ) const

◆ FloatToString()

static String FloatToString	(	Float	v,
		Int32	vvk = `-1`,
		Int32	nnk = `-1`,
		Bool	e = `false`,
		UInt16	xchar = `'0'`
	)

static

Converts a Float into a String.

Parameters

[in]	v	The Float value to convert.
[in]	vvk	The number of digits in front of the comma.
[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 Float as a String.

◆ IntToString() [1/2]

static String IntToString ( Int32 v )

static

Converts an Int32 into a String.

Parameters

[in] v The 32-bit integer value to convert.

Returns: The Int32 as a String.

◆ UIntToString() [1/2]

static String UIntToString ( UInt32 v )

static

Converts a UInt32 into a String.

Parameters

[in] v The 32-bit unsigned integer value to convert.

Returns: The UInt32 as a String.

◆ IntToString() [2/2]

static String IntToString ( Int64 v )

static

Converts an Int64 into a String.

Parameters

[in] v The 64-bit integer value to convert.

Returns: The Int64 as a String.

◆ UIntToString() [2/2]

static String UIntToString ( UInt64 v )

static

Converts an UInt64 to a String.

Parameters

[in] v The 64-bit unsigned integer value to convert.

Returns: The UInt64 as a String.

◆ VectorToString() [1/2]

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

static

Converts a Vector32 to a String.

Parameters

[in]	v	The 32-bit vector 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 to a String.

Parameters

[in]	v	The 64-bit vector value to convert.
[in]	nnk	The number of digits after the comma.

Returns: The Vector64 as a String.

◆ ToUpper()

const String ToUpper ( ) const

Converts the characters of the string to uppercase. This will only work with ANSI characters less than character code 128, all other characters will remain unchanged.

Note: Returns a copy of the string.

Returns: The converted uppercase string.

◆ ToLower()

const String ToLower ( ) const

Converts the characters of the string to lowercase. This will only work with ANSI characters less than character code 128, all other characters will remain unchanged.

Note: Returns a copy of the string.

Returns: The converted lowercase string.

◆ GetCStringLen()

Int32 GetCStringLen ( STRINGENCODING type = STRINGENCODING_XBIT ) const

Gets the expected length of the string after encoding.

Parameters

[in] type Type of string encoding.

Returns: The length of the string.

◆ GetCString()

Int32 GetCString	(	Char *	cStr,
		Int32	max,
		STRINGENCODING	type = `STRINGENCODING_XBIT`
	)		const

Gets the string after encoding. This routine can be used to convert Cinema 4D Unicode strings into standard C strings.

Parameters

[out]	cStr	Buffer for the encoded string. The size of the buffer must be at least Max. The caller owns the pointed buffer..
[in]	max	Maximum number of characters for the buffer Cstr. Should be GetCStringLen() + 1.
[in]	type	Type of string encoding.

Returns: The length of the string.

◆ SetCString()

Int32 SetCString	(	const Char *	cStr,
		Int32	count = `-1`,
		STRINGENCODING	type = `STRINGENCODING_XBIT`
	)

Gets the string from an encoded string. This routine converts a standard C string into a Cinema 4D Unicode string.

Parameters

[out]	cStr	Buffer containing the encoded string. The caller owns the pointed buffer..
[in]	count	The number of characters in the encoded string, or -1 to use the '\0' termination.
[in]	type	Type of string encoding.

Returns: The length of the string.

◆ GetCStringCopy()

Char* GetCStringCopy ( STRINGENCODING type = STRINGENCODING_XBIT ) const

Gets a standard C string copy of the string.

Warning: The return C string has to be freed by the caller after use.

Parameters

[in] type Type of string encoding.

Returns: The C string copy of the string. Important: The C string buffer has to be freed after usage.

◆ GetUcBlockNull()

void GetUcBlockNull	(	UInt16 *	ubc,
		Int32	max
	)		const

Gets the Unicode data of the string directly, without having to access the [] operator (which is slower).

Note: This version adds a '\0' character at the end of the string.

See also: GetUcBlock()

Parameters

[out]	ubc	Should point to a buffer to be filled with the Unicode data of the string. The caller owns the pointed buffer..
[in]	max	Maximum number of elements to fill in Ubc, including the '\0' terminator.

◆ GetUcBlockNullCopy()

UInt16* GetUcBlockNullCopy ( ) const

Gets the copy of the Unicode data, without having to access the [] operator (which is slower).

Note: This version adds a '\0' character at the end of the string.

See also: GetUcBlock()

Returns: The copy of the Unicode data of the string. Important: The memory buffer has to be freed after usage.

◆ GetUcBlock()

void GetUcBlock	(	UInt16 *	ubc,
		Int32	max
	)		const

Gets the Unicode data of the string directly, without having to access the [] operator (which is slower).

Note: This version does not add a '\0' character at the end of the string.

See also: GetUcBlockNull()

Parameters

[in]	ubc	Should point to a buffer to be filled with the Unicode data of the string. The caller owns the pointed buffer..
[in]	max	Maximum number of elements to fill in Ubc.

◆ SetUcBlock()

void SetUcBlock	(	const UInt16 *	ubc,
		Int32	count
	)

Sets the Unicode data into the string directly.

Parameters

[in]	ubc	A buffer with the Unicode data to set. The caller owns the pointed buffer..
[in]	count	The number of elements in Ubc.

◆ GetDataPtr()

Int32 GetDataPtr ( const UInt16 ** outPtr ) const

Gets a pointer to the string data.

Parameters

[out] outPtr Assigned a pointer to the string data.

Returns: The length of the string.

◆ operator[]() [1/2]

const PChar operator[] ( Int32 pos ) const

Get/Set Operators Gets a constant Unicode character from the string at position pos.

Parameters

[in] pos The position within the string to get the character at. Must be 0 <= Pos < GetLength().

Returns: The character.

◆ operator[]() [2/2]

PChar operator[] ( Int32 pos )

Gets a non-constant Unicode character from the string at a position. This makes it possible to assign to a character position:

String s("Hello World!");

s[1] = 'a';

Parameters

[in] pos The position within the string to get the character at. Must be 0 <= Pos < GetLength().

Returns: The character.

Friends And Related Function Documentation

◆ String::PChar

friend class String::PChar

friend

◆ operator+

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

friend

Concatenates two strings and return the resulting string.

Parameters

[in]	str1	The left-hand operand string.
[in]	str2	The right-hand operand string.

Returns: The concatenated string.

Member Data Documentation

◆ Size

Int32 Size

private

The actual allocated size. Private. Internal.

◆ Len

Int32 Len

private

The number of characters. Private. Internal.

◆ Txt

UInt16* Txt

private

The string text data. Private. Internal.

◆ future_enhancements

void* future_enhancements

private

Private. Internal.

Classes

Public Member Functions

Protected Member Functions

Private Attributes

Friends

Constructors/Destructors

Operators

Comparison

Find

Delete/Insert/SubStr

Parse to Number

Conversion from Number

Convert to Upper/Lower Case

C and Unicode String Conversion

Detailed Description

Constructor & Destructor Documentation

◆ String() [1/6]

◆ String() [2/6]

◆ String() [3/6]

◆ String() [4/6]

◆ String() [5/6]

◆ String() [6/6]

◆ ~String()

Member Function Documentation

◆ IncSize()

◆ GetLength()

◆ IsPopulated()

◆ Init()

◆ ShrinkToLen()

◆ operator=()

◆ operator+=()

◆ operator<()

◆ operator>()

◆ operator<=()

◆ operator>=()

◆ operator==()

◆ operator!=()

◆ Compare()

◆ ComparePart()

◆ LexCompare()

◆ RelCompare()

◆ FindFirst() [1/2]

◆ FindLast() [1/2]

◆ FindFirst() [2/2]

◆ FindLast() [2/2]

◆ FindFirstUpper()

◆ FindLastUpper()

◆ Delete()

◆ Insert() [1/2]

◆ Insert() [2/2]

◆ SubStr()

◆ Left()

◆ Right()

◆ ParseToInt32()

◆ FloatToString()

◆ IntToString() [1/2]

◆ UIntToString() [1/2]

◆ IntToString() [2/2]

◆ UIntToString() [2/2]

◆ VectorToString() [1/2]

◆ VectorToString() [2/2]

◆ ToUpper()

◆ ToLower()

◆ GetCStringLen()

◆ GetCString()

◆ SetCString()

◆ GetCStringCopy()

◆ GetUcBlockNull()

◆ GetUcBlockNullCopy()

◆ GetUcBlock()

◆ SetUcBlock()

◆ GetDataPtr()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

Friends And Related Function Documentation

◆ String::PChar

◆ operator+

Member Data Documentation

◆ Size

◆ Len