String Manual (Classic)

About

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

Note
Cinema 4D strings are fully using UTF-32 Unicode characters. To avoid problems with Unicode try to always use Utf32Char unless it is needed to interface with the system or existing libraries.
Use ApplicationOutput() to print strings to the Cinema 4D "Console" window.
The std::string class of the standard library should only be used if absolutely necessary.
Warning
String is based on maxon::String. More information on maxon::String is found here: String Manual.

Access

String objects can be created on demand or can be obtained from other entities.

To retrieve and modify String objects stored in a BaseContainer respectively use:

See also BaseContainer Manual.

To retrieve and modify String objects stored in a GeData object (GeData type is DA_STRING) respectively use:

See also GeData Manual.

// This example reads the name of the given BaseObject using the "Name" parameter.
BaseObject* const object = doc->GetActiveObject();
if (object == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
GeData data;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ApplicationOutput("Active Object: " + data.GetString());

Strings are also registered in resource files. Each of these strings has an ID in cd4_symbols.h and is defined in a *.str file in the string folder of a specific language. This way a plugin can easily be localized by adding str files for each supported language.

  • GeLoadString(): Returns a string from the resource files. Different versions of GeLoadString() allow to replace the placeholders in the string with custom content.
// This example loads a string from the plugin's string resources.
const String string = GeLoadString(IDS_TESTSTRING);
Note
A plugin must load its resources in PluginMessage() to use GeLoadString(). See Initialize Resources.

If it is needed that the user enters or edits a String a special dialog can be used:

Copy

A String can be copied with the default operator:

// This example copies a String.
const String content { "foobar" };
String empty = "";
empty = content;

Combine

Multiple String objects can be combined with the usual operators:

// This example merges two strings using
// different operators.
String foo = "foo";
String bar = "bar";
const String fooBar = foo + bar;
String helloWorld = "hello";
helloWorld += " world";
ApplicationOutput(helloWorld);

Find String

The String class provides functions to find substrings in a given string or character:

// This example searches for a substring in the given string
// and prints the position of the first occurrence.
const String fooBar = "fooBar";
Int32 pos = 0;
// search for substring "Bar"
if (fooBar.FindFirst("Bar", &pos))
ApplicationOutput("Found at position " + String::IntToString(pos));

Substrings

The String class provides functions to return substrings of a given string:

// This example creates various substrings of the given String and changes it.
String aliceBob("Alice and Bob");
// prints "Alice"
ApplicationOutput(aliceBob.Left(5));
// prints "Bob"
ApplicationOutput(aliceBob.Right(3));
// prints "and"
ApplicationOutput(aliceBob.SubStr(6, 3));
// removes "and"
aliceBob.Delete(6, 3);
// adds a "+"
aliceBob.Insert(6, '+') iferr_return;
// prints "Alice + Bob"
ApplicationOutput(aliceBob);

It is also possible to accesses a single character directly:

  • String::operator[](): Sets or gets a constant Unicode character from the string at the given position.
// This example accesses a single character directly.
String string("define");
string[0] = 'r';

Compare

The String class provides functions to compare to String objects:

Convert

Note
MAXON API data types typically implement a ToString() function.

To Numbers

A string can be converted to a number when the stored characters describe a number. This might be useful for example to handle user input:

// This example converts the given String into a Float value.
const String gigawatts = "1.21";
Int32 error = 0;
Float gigawattsFloat = gigawatts.ParseToFloat(&error);
if (error != 0)
{
// could not convert string to float
}

Also a more generic function is available:

From Numbers

Several static functions can be used to convert both 32 and 64 bit numbers to strings:

// This example prints the address and size of the given memory block to the console.
const UInt memoryAdress = (UInt)memory;
ApplicationOutput("Memory adress: " + String::HexToString(memoryAdress));

Also:

// This example prints the given float value as a percentage including the "%" symbol.
const Float percentage = 0.23;
const String formattedString = FormatNumber(percentage, FORMAT_PERCENT, 24);
ApplicationOutput(formattedString);

Upper and Lower Case

A typical string operation is to convert all characters to upper or lowercase characters. These functions only work with ANSI characters less than character code 128, all other characters remain unchanged:

// This example converts the given String to upper case characters.
const String string { "foobar" };
ApplicationOutput(string.ToUpper());

C string

Sometimes strings must be communicated with other libraries. In this case it is needed to convert a Cinema 4D String into a standard string:

// This example converts the given String into a C-String to use it with the standard library.
const String string { "foobar" };
// convert to c string and insert into std string.
Char* cstring = string.GetCStringCopy();
std::string stdString { cstring };
DeleteMem(cstring);

Filename

The Filename class is used to handle filenames and paths. Its content can be defined with strings and be converted to strings:

See also Filename Manual.

// This example opens the file select dialog and prints the path,
// the filename and suffix of the selected file.
Filename selectFile;
// open file selector dialog
if (selectFile.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Select File"_s))
{
ApplicationOutput("File selected: " + selectFile.GetString());
ApplicationOutput("File: " + selectFile.GetFileString());
ApplicationOutput("Suffix: " + selectFile.GetSuffix());
}

Date & Time

The class DateTimeParser can be used to parse and create date time strings.

// This example defines the formatting date and time
// and prints the current date and time to the console.
if (dtp == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const String date = dtp->MakeString(dt, DATETIMEPARSERMODE::DATE);
const String time = dtp->MakeString(dt, DATETIMEPARSERMODE::TIME);
ApplicationOutput(date + " " + time);

Similar functionality is also provided by functions of the datetime library:

// This example uses the simple functions to print the current date and time to the console.

Disc I/O

A String object can be stored in a BaseFile or a HyperFile using:

// This example writes the string into a new BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to write
if (!bf->Open(filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
bf->WriteString(string);
bf->Close();
// This example reads a String form the given BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to read
if (!bf->Open(filename, FILEOPEN::READ, FILEDIALOG::ANY))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
String string;
bf->ReadString(&string);
ApplicationOutput("String from BaseFile: " + string);
bf->Close();
// This example writes the string into a new HyperFile.
if (hf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to write
if (hf->Open(789, filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
hf->WriteString(string);
hf->Close();
// This example reads a String from the given HyperFile.
if (hf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to read
if (!hf->Open(789, filename, FILEOPEN::READ, FILEDIALOG::ANY))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
String string;
hf->ReadString(&string);
ApplicationOutput("String from HyperFile: " + string);
hf->Close();

See also BaseFile Manual on String and HyperFile Manual on String.

Regular Expressions

Regular expressions are used to check if a given string matches a certain pattern. The class RegularExprParser provides basic functionality to parse for simple expressions:

The parser is used with these functions:

// This example checks if the given String is a filename containing the "jpg" suffix.
// If so, the full name is printed to the console.
if (regEx == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
String strSerial;
Int32 pos;
// define expression
const String anyChar = String(1, ANY_CHAR);
String expression("(" + anyChar + "*)(.jpg)");
regEx->Init(expression);
// check string
if (regEx->FindFirst(filename, REGPARSEMODE::CONTAINS, false, pos, strSerial))
ApplicationOutput(strSerial);
else
ApplicationOutput("Expression does not match.");

Special Characters

Some symbols may be OS depended. These functions exist to get the correct symbol in each environment:

// This example prints the given percentage value using the "%" symbol.
const Int32 percentage = 55;
ApplicationOutput("Percentage: " + String::IntToString(percentage) + GeGetPercentChar());

Further Reading

BaseFile::Close
Bool Close()
String::HexToString
static String HexToString(UInt32 v, Bool prefix0x=true)
Definition: c4d_string.h:475
RegularExprParser::Init
Bool Init(const String &strExprssion)
DATETIMEPARSERMODE::TIME
@ TIME
Time.
HyperFile::WriteString
Bool WriteString(const maxon::String &v)
BaseFile::ReadString
Bool ReadString(maxon::String *v)
FormatNumber
String FormatNumber(const GeData &val, Int32 format, Int32 fps, Bool bUnit=true)
BaseObject
Definition: c4d_baseobject.h:220
DescID
Definition: lib_description.h:315
Filename::GetSuffix
String GetSuffix(void) const
FILEDIALOG::ANY
@ ANY
Show an error dialog for any error.
ANY_CHAR
#define ANY_CHAR
Any character = ASCII 2.
Definition: lib_regexpr.h:20
FORMAT_PERCENT
@ FORMAT_PERCENT
Floating point with % sign, 1.0 = 100%.
Definition: c4d_gui.h:36
Float
maxon::Float Float
Definition: ge_sys_math.h:51
DateTimeParser::SetFormatString
void SetFormatString(const String &sFormat, DATETIMEPARSERMODE mode)
String::GetCStringCopy
Char * GetCStringCopy(STRINGENCODING type=STRINGENCODING::XBIT) const
REGPARSEMODE::CONTAINS
@ CONTAINS
Partial match.
Filename
Manages file and path names.
Definition: c4d_file.h:81
GetDateTimeNow
void GetDateTimeNow(DateTime &t)
FILESELECTTYPE::ANYTHING
@ ANYTHING
Any file.
String::FindFirst
Bool FindFirst(const String &cs, Int32 *pos, Int start=0) const
Definition: c4d_string.h:277
iferr_return
#define iferr_return
Definition: resultbase.h:1434
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
BaseFile::Open
Bool Open(const Filename &name, FILEOPEN mode=FILEOPEN::READ, FILEDIALOG error_dialog=FILEDIALOG::IGNOREOPEN, BYTEORDER order=BYTEORDER::V_MOTOROLA, Int32 type='C4DC', Int32 creator='C4D1')
DateTimeParser::MakeString
String MakeString(const DateTime &dt, DATETIMEPARSERMODE mode)
HyperFile::Open
Bool Open(Int32 ident, const Filename &filename, FILEOPEN mode, FILEDIALOG error_dialog)
Filename::GetString
String GetString(void) const
String
Definition: c4d_string.h:35
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:492
String::ParseToFloat
Float ParseToFloat(Int32 *error=nullptr, Int unit=0, Int angletype=0, Int base=10) const
Definition: c4d_string.h:438
FILEOPEN::WRITE
@ WRITE
DateTime
Represents a date and time.
Definition: customgui_datetime.h:34
GeLoadString
const String & GeLoadString(Int32 id)
maxon::DeleteMem
void DeleteMem(T *&p)
Definition: defaultallocator.h:258
DATETIMEPARSERMODE::DATE
@ DATE
Date.
Filename::GetFileString
String GetFileString(void) const
GeData
Definition: c4d_gedata.h:77
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:45
HyperFile::ReadString
Bool ReadString(maxon::String *v)
BaseFile::WriteString
Bool WriteString(const maxon::String &v)
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:209
DateToString
String DateToString(const DateTime &d)
GeData::GetString
const String & GetString(void) const
Definition: c4d_gedata.h:447
FILESELECT::LOAD
@ LOAD
Load dialog.
FILEOPEN::READ
@ READ
Open the file for reading.
GeGetPercentChar
String GeGetPercentChar()
HyperFile::Close
Bool Close()
ID_BASELIST_NAME
@ ID_BASELIST_NAME
Definition: obaselist.h:7
AutoAlloc
Definition: ge_autoptr.h:32
DESCFLAGS_GET::NONE
@ NONE
None.
TimeToString
String TimeToString(const DateTime &d, const Bool bShowSeconds=true)
BaseDocument::GetActiveObject
BaseObject * GetActiveObject(void)
UInt
maxon::UInt UInt
Definition: ge_sys_math.h:50
Char
maxon::Char Char
Definition: ge_sys_math.h:41
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
RegularExprParser::FindFirst
Bool FindFirst(const String &strText, REGPARSEMODE mode, Bool bOnlyFirst, Int32 &lPos, String &strPattern)
Filename::FileSelect
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())