String Class Reference

#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.