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:

BaseContainer::GetString(): Returns the String stored at the given ID.
BaseContainer::SetString(): Sets the String stored at the given ID.

Copy

A String can be copied with the default operator:

String::operator=(): Assigns the content of the String to the other String object.

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

Combine

Multiple String objects can be combined with the usual operators:

String::operator+(): Combines two strings and returns the result string.
String::operator+=(): Concatenates the strings and sets the left-hand operand to the result.

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

Find String

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

String::FindFirst: Searches the string for the first match of a given substring.
String::FindFirstUpper(): Searches the string for the first match of the upper-case substring.
String::FindLast(): Searches the string for the last match of the substring.
String::FindLastUpper(): Searches the string for the last match of the upper-case substring.

  // 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:

String::SubStr(): Returns a substring from the string.
String::Left(): Returns a substring from the left of the string.
String::Right(): Returns a substring from the right of the string.
String::Delete(): Removes a section from the 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';
 
  ApplicationOutput(string);

Compare

The String class provides functions to compare to String objects:

String::Compare(): Compare the strings and returns their relationship.
String::ComparePart(): Compares a part of the string.
String::LexCompare(): Compares the String object with another string and returns their relationship.
String::LexComparePart(): Compares a part of the string with the given string and returns their relationship

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:

String::ParseToFloat(): Converts the string into a ::Float value.
String::ParseToInt32(): Converts the string into an ::Int32 value.
String::ToInt32(): Converts the string to an ::Int32 value.
String::ToInt64(): Converts the string to an ::Int64 value.
String::ToUInt32(): Converts the string to a ::UInt32 value.
String::ToUInt64(): Converts the string to a ::UInt64 value.
String::ToFloat(): Converts the string to a ::Float value.
String::ToInt(): Converts the string to an ::Int value.
String::ToUInt(): Converts the string to a ::UInt value.

  // 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:

StringToNumber(): Converts a string to a data value of type ::Float, ::Int32 or ::BaseTime.

From Numbers

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

String::MemoryToString(): Converts the number to a memory size.
String::HexToString(): Converts the number to a hexadecimal representation.
String::IntToString(): Converts the given integer value to a string.
String::UIntToString(): Converts the given unsigned integer value to a string.
String::FloatToString(): Converts the given float value to a string.
String::VectorToString(): Converts the given vector to a string.

    // 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:

FormatNumber(): Converts a ::Float, ::Int32 or ::BaseTime to a formatted string.

    // 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:

String::ToUpper(): Returns the string converted to upper case characters.
String::ToLower(): Returns the string converted to lower case characters.

    // 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:

String::GetCStringLen(): Gets the expected length of the string after encoding.
String::GetCString(): Gets the string after encoding.
String::GetCStringCopy(): Gets the encoded string as a copy.
String::SetCString(): Sets the string from a given standard C 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:

Filename::GetString(): Returns the full filename as a String.
Filename::SetString(): Sets the filename with the given String.
Filename::GetFileString(): Returns the file part of the filename as a String.
Filename::GetSuffix(): Returns the file suffix as a String.

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.
 
    AutoAlloc<DateTimeParser> dtp;
    if (dtp == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    dtp->SetFormatString("YYYY-MM-DD", DATETIMEPARSERMODE::DATE);
    dtp->SetFormatString("HH-MM-SS", DATETIMEPARSERMODE::TIME);
 
    DateTime dt;
    GetDateTimeNow(dt);
 
    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:

ParseTimeString(): Parses the time defined in the given String.
ParseDateString(): Parses the date defined in the given String.
FormatTime(): Returns a String with the formatted time. It uses the same arguments as the asctime() function of the standard library.
TimeToString(): Returns a String with the formatted time.
DateToString(): Returns a String with the formatted date.
GetMonthName(): Returns a String with the name of the given month.

    // This example uses the simple functions to print the current date and time to the console.
 
    DateTime dt;
    GetDateTimeNow(dt);
 
    ApplicationOutput(DateToString(dt) + " " + TimeToString(dt));

Disc I/O

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

BaseFile::ReadString(): Reads a String from the BaseFile.
BaseFile::WriteString(): Writes a String into the BaseFile.

  // This example writes the string into a new BaseFile.
 
  AutoAlloc<BaseFile> bf;
  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.
 
    AutoAlloc<BaseFile> bf;
    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();

HyperFile::ReadString(): Reads a String from the HyperFile.
HyperFile::WriteString(): Writes a String into the HyperFile.

  // This example writes the string into a new HyperFile.
 
  AutoAlloc<HyperFile> hf;
  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.
 
    AutoAlloc<HyperFile> hf;
    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:

RegularExprParser::Alloc(): Allocates a regular expression parser.
RegularExprParser::Free(): Frees a regular expression parser.

The parser is used with these functions:

RegularExprParser::Init(): Initializes the parser with the given regular expression.
RegularExprParser::FindFirst(): Performs a search using the regular expression passed to RegularExprParser::Init() in the given string and returns the position of the first match.
RegularExprParser::FindNext(): Returns the position of further matches.
RegularExprParser::CleanUp(): Cleans the memory allocated by RegularExprParser::Init().

  // This example checks if the given String is a filename containing the "jpg" suffix.
  // If so, the full name is printed to the console.
 
  AutoAlloc<RegularExprParser> regEx;
  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:

GeGetDegreeChar(): Returns the degree character.
GeGetPercentChar(): Returns the percent character.
GeGetLineEnd(): Returns a string that contains the type of line ending characters for the running OS.

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

Table of Contents