FormatStatement Manual

Table of Contents

• About
• Class
• ToString
• Usage
• Further Reading

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.

• maxon::FormatStatement::FormatStatement(): Creates a new maxon::FormatStatement object.
• maxon::FormatStatement::Get(): Returns the string stored at the given identifier.
• maxon::FormatStatement::Set(): Stores a string at the given identifier.
• maxon::FormatStatement::operator=(): Copies the data from the given maxon::FormatStatement.

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
    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.

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
 
  maxon::FormatStatement longFormat;
  longFormat.Set("Format"_cs, "Long"_cs) iferr_return;
 
  const maxon::String longFormatString = triplet.ToString(&longFormat);
  DiagnosticOutput("@", longFormatString);
 
  // short format
 
  maxon::FormatStatement shortFormat;
  shortFormat.Set("Format"_cs, "Short"_cs) iferr_return;
 
  const maxon::String shortFormatString = triplet.ToString(&shortFormat);
  DiagnosticOutput("@", shortFormatString);
 
  // default format
 
  DiagnosticOutput("@", triplet);

Further Reading

• Data Manual
• String Manual