String Manual (Classic)

Table of Contents

• About
• Access
• Copy
• Combine
• Find String
• Substrings
• Compare
• Convert
  • To Numbers
  • From Numbers
  • Upper and Lower Case
  • C string
  • Filename
  • Date & Time
• Disc I/O
• Regular Expressions
• Special Characters
• Further Reading

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.

See also BaseContainer Manual.

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

• GeData::GetString(): Returns the String object.
• GeData::SetString(): Stores the String object.

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;
 
  if (!object->GetParameter(ConstDescID(DescLevel(ID_BASELIST_NAME)), data, DESCFLAGS_GET::NONE))
    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);
 
  ApplicationOutput(string);

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:

• RenameDialog(): Opens a dialog that presents a String and allows the user to edit this String.

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.

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.
 
    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());

Further Reading

• GeData Manual
• BaseContainer Manual
• Primitive Data Types Manual (Classic)
• Vector Manual (Classic)
• Matrix Manual (Classic)
• Filename Manual