FormatStatement Manual


Typically a MAXON API interface or a data type defines a "ToString()" function. This function returns a maxon::String describing the given object. Such a "ToString()" function accepts a maxon::FormatStatement argument that can contain additional information on how the object should be described.


A maxon::FormatStatement object contains string stored under a given string identifier.


A "ToString()" function can read information from the given maxon::FormatStatement to define how it formats the returned maxon::String.

// This example shows an implementation of ToString() on a custom data type.
// The function formats the result maxon::String based on the given FormatStatement argument.
maxon::String ToString(const maxon::FormatStatement* formatStatement = nullptr) const
maxon::Bool longFormat = false;
// check FormatStatement
if (formatStatement)
const maxon::CString format = formatStatement->Get("Format");
if (!format.IsEmpty())
longFormat = format.Find(maxon::CString("Long"), 0);
// format result
maxon::String result;
if (longFormat)
result = FormatString("Value A: @, Value B: @, Value C: @", _a, _b, _c);
result = FormatString("@, @, @", _a, _b, _c);
// return formatted string
return result;
maxon::String ToString(const Filename &val, const maxon::FormatStatement *formatStatement, maxon::Bool checkDatatype=false)
Definition: string.h:1446
Bool IsEmpty() const
Definition: string.h:1543
Class to store formatting statements.
Definition: string.h:1975
Definition: string.h:1207
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:182
#define FormatString(...)
Definition: string.h:2045


When calling a "ToString()" function the call can hand over a maxon::FormatStatement argument to modify the behaviour of the function.

For more information about the output syntax see Output Syntax.

Not all "ToString()" functions do handle the maxon::FormatStatement argument. When a function does not handle the argument, a nullptr can be handed over.
// This example prints the data of the given data type to the debug console.
// The behaviour of ToString() is controlled via FormatStatement arguments.
FloatTriplet triplet;
triplet._a = 1.1;
triplet._b = 1.2;
triplet._c = 1.3;
// long format
longFormat.Set("Format"_cs, "Long"_cs) iferr_return;
const maxon::String longFormatString = triplet.ToString(&longFormat);
DiagnosticOutput("@", longFormatString);
// short format
shortFormat.Set("Format"_cs, "Short"_cs) iferr_return;
const maxon::String shortFormatString = triplet.ToString(&shortFormat);
DiagnosticOutput("@", shortFormatString);
// default format
DiagnosticOutput("@", triplet);
Result< void > Set(const Char *identifier, const CString &str)
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
#define iferr_return
Definition: resultbase.h:1434

Further Reading