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
 
UInt16Txt
 
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 String operator+ (const String &str1, const String &str2)
 
const Stringoperator= (const String &str)
 
const Stringoperator+= (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
 

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)
 
CharGetCStringCopy (STRINGENCODING type=STRINGENCODING_XBIT) const
 
void GetUcBlockNull (UInt16 *ubc, Int32 max) const
 
UInt16GetUcBlockNullCopy () 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]strThe 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]cStrThe character array to initialize the string from. Must be formatted using the STRINGENCODING_XBIT scheme. The pointed array is copied.
[in]typeThe string encoding.

◆ String() [4/6]

String ( const UInt16 uStr)

Constructs the string with the Unicode characters in Ustr.

Parameters
[in]uStrThe 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]uStrThe Unicode character array to initialize the string from. The pointed array is copied.
[in]countThe length of Ustr string.

◆ String() [6/6]

String ( Int32  count,
UInt16  fillChar 
)

Constructs a string filled with the same character.

Parameters
[in]countThe number of characters.
[in]fillCharThe 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]countThe length of the string.
[in]fillCharThe 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]strThe 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]strThe 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]strThe 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]strThe 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]strThe 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]strThe 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]strThe 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]strThe 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]strThe 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]strThe string to compare against.
[in]countThe number of characters of the part.
[in]posThe 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]strThe 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]strThe 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]strSubstring to search for.
[in]posPointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]startStarting 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]strSubstring to search for.
[in]posPointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]startPosition 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]chThe character to find.
[in]posPointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]startStarting 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]chThe character to find.
[in]posPointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]startPosition 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]findUpperUpper-case substring to search for.
[in]posPointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]startStarting 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]findUpperUpper-case substring to search for.
[in]posPointer to an Int32 to receive the found position in the string. The caller owns the pointed integer..
[in]startPosition 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]posStarting position to remove. Must be 0 <= Pos < GetLength().
[in]countNumber 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]posPosition to insert the string. Must be 0 <= Pos < GetLength().
[in]strString to insert.
[in]startStart position within the inserted string to only insert parts of the string.
[in]endEnd 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]posPosition to insert the character. Must be 0 <= Pos < GetLength().
[in]chCharacter to insert.

◆ SubStr()

const String SubStr ( Int32  start,
Int32  count 
) const

Extracts a substring from the String.

Parameters
[in]startPosition to extract the substring from. Must be 0 <= Pos < GetLength().
[in]countNumber of characters of the substring. Must be 0 <= Count < GetLength()-Start.
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]vThe Float value to convert.
[in]vvkThe number of digits in front of the comma.
[in]nnkThe number of digits after the comma.
[in]eSet to true to use exponential writing.
[in]xcharThe 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]vThe 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]vThe 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]vThe 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]vThe 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]vThe 32-bit vector value to convert.
[in]nnkThe 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]vThe 64-bit vector value to convert.
[in]nnkThe 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]typeType 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]cStrBuffer for the encoded string. The size of the buffer must be at least Max. The caller owns the pointed buffer..
[in]maxMaximum number of characters for the buffer Cstr. Should be GetCStringLen() + 1.
[in]typeType 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]cStrBuffer containing the encoded string. The caller owns the pointed buffer..
[in]countThe number of characters in the encoded string, or -1 to use the '\0' termination.
[in]typeType 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]typeType 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]ubcShould point to a buffer to be filled with the Unicode data of the string. The caller owns the pointed buffer..
[in]maxMaximum 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]ubcShould point to a buffer to be filled with the Unicode data of the string. The caller owns the pointed buffer..
[in]maxMaximum 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]ubcA buffer with the Unicode data to set. The caller owns the pointed buffer..
[in]countThe number of elements in Ubc.

◆ GetDataPtr()

Int32 GetDataPtr ( const UInt16 **  outPtr) const

Gets a pointer to the string data.

Parameters
[out]outPtrAssigned a pointer to the string data.
Returns
The length of the string.

◆ operator[]() [1/2]

const PChar operator[] ( Int32  pos) const

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

Parameters
[in]posThe 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]posThe 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 String operator+ ( const String str1,
const String str2 
)
friend

Concatenates two strings and return the resulting string.

Parameters
[in]str1The left-hand operand string.
[in]str2The 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.