String Manual

About

maxon::String is the universal string class of the MAXON API. Is is based on maxon::StringInterface and maxon::StringTemplate.

Note
The classic String class is based on maxon::String. See String Manual (Classic).

Creation and Construction

A maxon::String can easily be created on the stack and constructed using the "+=" operator:

Note
A constant maxon::String can also be created using the "_s" operator.
// This example creates and constructs a simple maxon::String.
// create the string
maxon::String message("Hello");
// extend the string
message += maxon::String(" ");
message += "World!"_s;

A maxon::String can also be constructed with:

// This example creates a string and adds to it.
// create string
maxon::String message;
// init
message.Init(2, '9') iferr_return;
// append
message.Append(" bottles of beer on the wall"_s) iferr_return;
message.AppendChar('!') iferr_return;

Integer values can be added to the maxon::String with:

// This example creates a string and adds a number to it
maxon::String message;
message.AppendInt(maxon::Int(99));
message.Append(" bottles of beer!"_s) iferr_return;

A maxon::String can also be constructed with FormatString().

// This example function creates a new String based on the input data.
static maxon::String FormatObjectData(const maxon::String objectName, maxon::Int polyCount, maxon::Int pointCount)
{
const maxon::String res = FormatString("Object \"@\" (@ Polygons, @ Points)", objectName, polyCount, pointCount);
return res;
}

Output

A given maxon::String can easily printed to the debug console with DiagnosticOutput() or similar functions. See Debug and Output Functions.

Content

It is easily possible to iterate over all characters stored in a given maxon::String:

// This example prints each character of the given string to the debug console.
// some string
const maxon::String message("Hello World!");
// get each character
for (const maxon::Utf32Char& c : message)
{
str.AppendChar(c) iferr_return;
DiagnosticOutput("Character: @ (@)", str, c);
}

The content of the maxon::String can also be accessed with these functions:

// This example checks if the given string is empty. If not it will
// access and print each character to the debug console.
if (!message.IsEmpty())
{
const maxon::Int length = message.GetLength();
// get each character
for (maxon::Int i = 0; i < length; ++i)
{
// get character
const maxon::Utf32Char c = message[i];
str.AppendChar(c) iferr_return;
DiagnosticOutput("Character: @ (@)", str, c);
}
}

A maxon::String can be edited with:

// This example removes and adds character to the given string.
maxon::String message("Alice and Bob");
message.Erase(6, 3) iferr_return;
message.Insert(6, '&') iferr_return;

Conversion

A maxon::String can be converted to many other data formats but it also can be constructed by converting another data type to a maxon::String.

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

A maxon::String can be converted to a upper-case or lower-case version of itself:

See also MAXON_CONSTEXPR_TOLOWER.

// This example turns the given string into a lower-case string.
const maxon::String originalMessage("Hello World!");
const maxon::String lowerMessage = originalMessage.ToLower();
DiagnosticOutput(lowerMessage);

If the maxon::String describes a numeric value, this value can be converted to a numeric data type:

// This example converts the string into the numerical value it describes.
const maxon::String message("100.1");
maxon::Float floatValue = message.ToFloat() iferr_return;

Also numbers can be converted to a maxon::String:

See also maxon::StringConversion.

// This example converts the given number to a string representation.
const maxon::String value = maxon::String::FloatToString(maxon::Float(123.4));
maxon::String message("Value: ");
message += value;

If needed, a maxon::String can be converted to a C-string. This might be useful to convert it into std:string.

The content of the maxon::String can also be converted into special encodings:

Values of enumeration classes can be converted to maxon::String using a function template defined with the MAXON_ENUM_LIST / MAXON_ENUM_ORDERED_LIST attributes:

// This example compares two strings. The COMPARERESULT
// is converted to a string to print it to the console.
// compare strings
const maxon::COMPARERESULT res = textA.Compare(textB);
// print compare result
const maxon::String resStr = maxon::ToString<maxon::FormatStatement>(res, nullptr, false);
DiagnosticOutput("The string is @", resStr);

Further functions are:

Compare

A given maxon::String can be compared with another maxon::String:

The comparison modes are:

Note
To compare C-strings see maxon::CStringCompare.
// This example compares the two maxon::String objects. If they are not equal
// they are compared and the result is printed to the debug console.
if (!stringA.IsEqual(stringB))
{
const maxon::COMPARERESULT res = stringA.Compare(stringB);
DiagnosticOutput("Compare result: @", res);
}

Substring

A defined substring can be obtained from a given maxon::String.

Often it is useful to remove special characters like space, tab, line feed etc. from a maxon::String.

// This example removes white spaces from the given string and splits the result into two new strings.
maxon::String message(" Hello World. This is some string.");
// remove spaces
message.Trim() iferr_return;
// break down into sentences
message.Split("."_s, true, sentences) iferr_return;
for (const maxon::String& sentence : sentences)
DiagnosticOutput(sentence);

Search

A typical string operation is to check if a given maxon::String contains given substring.

// This example searches for the first occurrence of the given sub-string in the string.
// If found, the remaining part of the string is copied.
// check if http://
const maxon::String http("http://");
if (webAdress.Find(http, &pos))
{
maxon::String domain = webAdress.GetPart(http.GetLength(), maxon::StringEnd());
webAdress = "https://"_s;
webAdress.Append(domain) iferr_return;
}

Utility

Further utility functions are:

Utility Classes

Substring functions use maxon::StringPosition and maxon::StringCount to define the needed arguments.

StringPosition

A StringPosition object defines a position within a maxon::String.

// this example gets a sub-string of the given string and prints it to the debug console.
const maxon::String webAdress("https://www.maxon.net");
const maxon::StringPosition offset(8);
const maxon::String domain = webAdress.GetPart(offset, maxon::StringEnd());
DiagnosticOutput("Domain: @", domain);

StringCount

A StringCount object defines a range of characters within a maxon::String.

Further Reading