ST::formatter

string_theory formatter macros and definitions

Headers

#include <string_theory/formatter>

Macros

Name	Summary
ST_DECL_FORMAT_TYPE	Forward-declare a formatter for a given type
ST_FORMAT_TYPE	Declare and/or define a formatter for a given type
ST_FORMAT_FORWARD	Forward formatting to another formatter
ST_INVOKE_FORMATTER	Invoke the formatter for a given type

Details

This header provides the necessary macros and types for defining custom formatters. It must be included before any ST_DECL_FORMAT_TYPE or ST_FORMAT_TYPE definitions are created, but the definitions must not include <string_theory/format> or other consumers of the formatters until all custom formatters are declared.

Formatters for the following types are provided with string_theory:

Type	Comments
char	Single 7-bit ASCII character
wchar_t	Single wide character
signed char	Treated as a numeric type by default
unsigned char	Treated as a numeric type by default
short
unsigned short
int
unsigned int
long
unsigned long
long long
unsigned long long
float
double
bool	Formats as the literal string "true" or "false"
const char *
const wchar_t *
ST::string
std::complex	Since string_theory 1.1
std::filesystem::path	Since string_theory 1.1
std::string	Since string_theory 1.1
std::string_view	Since string_theory 2.0
std::wstring	Since string_theory 1.1
std::wstring_view	Since string_theory 2.0

For details on creating custom formatters, see the Custom formatter example.

Macro Documentation

ST_DECL_FORMAT_TYPE(type_T)

#define ST_DECL_FORMAT_TYPE(type_T) ...

Forward-declare a custom formatter. Note that this macro should be in the include chain AFTER <string_theory/formatter> is included, but BEFORE any format implementations (like <string_theory/format>) are included. However, it only needs to appear in the include chain if a caller needs to format the specified type_T.

See also ST_FORMAT_TYPE(type_T)

---

ST_FORMAT_FORWARD

#define ST_FORMAT_FORWARD(fwd_value) ...

Forward a value to another formatter. Note that the type of fwd_value must resolve to only one formatter, so a cast may be needed.

Example

ST_FORMAT_TYPE(const my_type &)
{
    // Assumes my_type::to_string() resolves to a string type we can format
    ST_FORMAT_FORWARD(value.to_string());
}

---

ST_FORMAT_TYPE

#define ST_FORMAT_TYPE(type_T) ...

Provides the necessary function header for implementing a custom formatter for the type type_T. Note that type_T should be a fully specified type, but should not include the variable name.

When writing a custom formatter using this header, the following parameters are available for use:

• const ST::format_spec &format: The format spec to be used for formatting the object.
• ST::format_writer &output: The output object for writing formatted text data.
• type_T value: The value object to format.

If this macro is used in a source file, there should be a matching ST_DECL_FORMAT_TYPE(type_T) in a header somewhere in order for it to be used by format engines. Alternatively, if you wish to declare the whole formatter in a header, this can be used directly with the inline specifier.

See also ST_DECL_FORMAT_TYPE(), Custom formatter example

---

ST_INVOKE_FORMATTER

#define ST_INVOKE_FORMATTER(format, output, value) ...

This macro should be called by custom format engines to invoke the formatter for a given object. It evaluates to the function call defined by either ST_DECL_FORMAT_TYPE() or ST_FORMAT_TYPE().