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 built in formatters below, as well as the necessary declarations and types for declaring custom formatters.

Formatters for the following types are provided with string_theory:

Type	Comments
char	Single 7-bit ASCII character. Changed in 3.0: Treated as numeric by default! Use {c} to format as a character.
char8_t	Single UTF-8 code point. Treated as numeric by default! Use {c} to format as a character. Since string_theory 3.0.
char16_t	Single UTF-16 code point. Treated as numeric by default! Use {c} to format as a character. Since string_theory 3.0.
char32_t	Single UTF-32 code point. Treated as numeric by default! Use {c} to format as a character. Since string_theory 3.0.
wchar_t	Single wide character. Changed in 3.0: Treated as numeric by default! Use {c} to format as a 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 char8_t *	Since string_theory 3.0
const char16_t *	Since string_theory 3.0
const char32_t *	Since string_theory 3.0
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::u8string	Since string_theory 3.0
std::u8string_view	Since string_theory 3.0
std::u16string	Since string_theory 3.0
std::u16string_view	Since string_theory 3.0
std::u32string	Since string_theory 3.0
std::u32string_view	Since string_theory 3.0
std::wstring	Since string_theory 1.1
std::wstring_view	Since string_theory 2.0

Note that as of string_theory 3.0, individual characters are treated as numeric types by default, due to the potential for type aliasing in some compilers or configurations. In order to format a single character as a character type, you must use the {c} format. See the Format String Reference guide for details.

Defining Custom Formatters

As of string_theory 3.0, formatters use argument dependent lookup, so they do not need to live in the ST namespace. To create a formatter, you should define an overload for format_type matching the interface:

// Given a formattable object of type MyType
void format_type(const ST::format_spec &format, ST::format_writer &output,
                 MyType value)
{
    ...
}

// Another example, using a const reference
void format_type(const ST::format_spec &format, ST::format_writer &output,
                 const MyType &value)
{
    ...
}

The format function can also call other format_type overloads if necessary to pass along formatting to another formatter. Note that all formatters provided by string_theory are in the ST namespace.

For an example of creating and using custom formatters, see the Custom formatter example.

Macro Documentation

ST_DECL_FORMAT_TYPE [deprecated]

#define ST_DECL_FORMAT_TYPE(type_T) \
    void format_type(const ST::format_spec &, ST::format_writer &, type_T)

Note: This is deprecated as of string_theory 3.0 and should not be used in new code. It is maintained for backwards compatibility, but may be removed in a future release of string_theory. Instead, you should define a format_type overload directly.

Forward-declare a custom formatter.

Deprecated in string_theory 3.0.

See also Defining Custom Formatters

---

ST_FORMAT_FORWARD [deprecated]

#define ST_FORMAT_FORWARD(fwd_value) \
    format_type(format, output, (fwd_value))

Note: This is deprecated as of string_theory 3.0 and should not be used in new code. It is maintained for backwards compatibility, but may be removed in a future release of string_theory.

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());
}

Deprecated in string_theory 3.0.

See also Defining Custom Formatters

---

ST_FORMAT_TYPE [deprecated]

#define ST_FORMAT_TYPE(type_T) \
    void format_type(const ST::format_spec &format, ST::format_writer &output, type_T value)

Note: This is deprecated as of string_theory 3.0 and should not be used in new code. It is maintained for backwards compatibility, but may be removed in a future release of string_theory. Instead, you should define a format_type overload directly.

Declare or define a custom formatter with the specified parameters.

Deprecated in string_theory 3.0.

See also Defining Custom Formatters

---

ST_INVOKE_FORMATTER [deprecated]

#define ST_INVOKE_FORMATTER format_type

Note: This is deprecated as of string_theory 3.0 and should not be used in new code. It is maintained for backwards compatibility, but may be removed in a future release of string_theory.

Deprecated in string_theory 3.0.

See also Defining Custom Formatters