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());
Definition: c4d_baseobject.h:248
Definition: c4d_gedata.h:83
const String & GetString() const
Definition: c4d_gedata.h:498
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
#define ConstDescID(...)
Definition: lib_description.h:594
@ ID_BASELIST_NAME
Definition: obaselist.h:7
const char * doc
Definition: pyerrors.h:226
Definition: object.h:105
Represents a level within a DescID.
Definition: lib_description.h:298

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);
const String & GeLoadString(Int32 id)
Definition: c4d_string.h:41
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));
static String IntToString(Int32 v)
Definition: c4d_string.h:497
Bool FindFirst(const String &cs, Int32 *pos, Int start=0) const
Definition: c4d_string.h:282
void Py_ssize_t * pos
Definition: dictobject.h:50
maxon::Int32 Int32
Definition: ge_sys_math.h:56

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);
#define iferr_return
Definition: resultbase.h:1524

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';
PyObject * string
Definition: asdl.h:6

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
}
Float ParseToFloat(Int32 *error=nullptr, Int unit=0, Int angletype=0, Int base=10) const
Definition: c4d_string.h:443
PyObject * error
Definition: codecs.h:206
maxon::Float Float
Definition: ge_sys_math.h:62

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));
static String HexToString(UInt32 v, Bool prefix0x=true)
Definition: c4d_string.h:480
maxon::UInt UInt
Definition: ge_sys_math.h:61

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);
String FormatNumber(const GeData &val, Int32 format, Int32 fps, Bool bUnit=true)
@ FORMAT_PERCENT
Floating point with % sign, 1.0 = 100%.
Definition: c4d_gui.h:47

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);
Char * GetCStringCopy(STRINGENCODING type=STRINGENCODING::XBIT) const
maxon::Char Char
Definition: ge_sys_math.h:52
void DeleteMem(T *&p)
Definition: defaultallocator.h:257

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());
}
Manages file and path names.
Definition: c4d_file.h:94
String GetString() const
String GetSuffix() const
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
String GetFileString() const
@ LOAD
Load dialog.
@ ANYTHING
Any file.

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);
dtp->SetFormatString("YYYY-MM-DD", DATETIMEPARSERMODE::DATE);
dtp->SetFormatString("HH-MM-SS", DATETIMEPARSERMODE::TIME);
const String date = dtp->MakeString(dt, DATETIMEPARSERMODE::DATE);
const String time = dtp->MakeString(dt, DATETIMEPARSERMODE::TIME);
ApplicationOutput(date + " " + time);
Definition: ge_autoptr.h:37
void GetDateTimeNow(DateTime &t)
Represents a date and time.
Definition: customgui_datetime.h:39

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.
String TimeToString(const DateTime &d, const Bool bShowSeconds=true)
String DateToString(const DateTime &d)

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
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
bf->WriteString(string);
bf->Close();
PyCompilerFlags const char * filename
Definition: ast.h:15
@ ANY
Show an error dialog for any error.
// This example reads a String form the given BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to read
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
bf->ReadString(&string);
ApplicationOutput("String from BaseFile: " + string);
bf->Close();
@ READ
Open the file for reading.
// This example writes the string into a new HyperFile.
if (hf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to write
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);
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;
// 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.");
@ CONTAINS
Partial match.
#define ANY_CHAR
Any character = ASCII 2.
Definition: lib_regexpr.h:24

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());
String GeGetPercentChar()

Further Reading