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 = 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
if (longFormat)
result = FormatString("Value A: @, Value B: @, Value C: @", _a, _b, _c);
else
result = FormatString("@, @, @", _a, _b, _c);
// return formatted string
return result;
}
const char * format
Definition: abstract.h:183
maxon::String ToString(const Filename &val, const maxon::FormatStatement *formatStatement, maxon::Bool checkDatatype=false)
Definition: string.h:1490
Class to store formatting statements.
Definition: string.h:2042
Definition: string.h:1235
PyObject PyObject * result
Definition: abstract.h:43
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:206
#define FormatString(...)
Definition: string.h:2112

Usage

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.

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);
Definition: formatstatement.h:10
maxon::String ToString(const maxon::FormatStatement *formatStatement=nullptr) const
[data_formatstring_tostring]
Definition: formatstatement.h:26
maxon::Float _c
Definition: formatstatement.h:21
maxon::Float _a
Definition: formatstatement.h:17
maxon::Float _b
Definition: formatstatement.h:20
Result< void > Set(const Char *identifier, const CString &str)
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
#define iferr_return
Definition: resultbase.h:1521

Further Reading