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 += "World!"_s;
Definition: string.h:1237
const char * message
Definition: pyerrors.h:189

A maxon::String can also be constructed with:

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

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

// This example creates a string and adds a number to it
message.AppendInt(maxon::Int(99));
message.Append(" bottles of beer!"_s) iferr_return;
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202

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;
}
Py_UCS4 * res
Definition: unicodeobject.h:1113
#define FormatString(...)
Definition: string.h:2168

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);
}
void * str
Definition: bytesobject.h:77
Py_UNICODE c
Definition: unicodeobject.h:1200
char32_t Utf32Char
Definition: apibase.h:228
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170

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
str.AppendChar(c) iferr_return;
DiagnosticOutput("Character: @ (@)", str, c);
}
}
Py_ssize_t i
Definition: abstract.h:645
PyWideStringList Py_ssize_t length
Definition: initconfig.h:448

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;
Float64 Float
Definition: apibase.h:211

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: " };
PyObject * value
Definition: abstract.h:715

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
DiagnosticOutput("The string is @", res);
COMPARERESULT
Data type for comparison results.
Definition: compare.h:21

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
// 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;
}
Definition: string.h:116
void Py_ssize_t * pos
Definition: dictobject.h:50
#define NOTOK
Definition: ge_sys_math.h:263

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);
Definition: string.h:74

StringCount

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

Further Reading