FormatStatement Manual

About

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.

Class

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

ToString

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) 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);
else
result = FormatString("@, @, @", _a, _b, _c);
// return formatted string
return result;
}

Usage

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

Note
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);

Further Reading