fmt.h File Reference

#include <string>
#include <string_view>
#include <type_traits>
#include <fmt/format.h>

Include dependency graph for fmt.h:

This graph shows which files directly or indirectly include this file:

Namespaces
	drake

Macros
#define	DRAKE_FMT8_CONST   const
	When using fmt >= 8, this is defined to be const to indicate that the fmt::formatter<T>::format(...) function should be object-const. More...
#define	DRAKE_FORMATTER_AS(TEMPLATE_ARGS, NAMESPACE, TYPE, ARG, EXPR)
	Adds a fmt::formatter<NAMESPACE::TYPE> template specialization that formats the TYPE by delegating the formatting using a transformed expression, as if a conversion function like this were interposed during formatting: More...

Functions
auto	fmt_runtime (std::string_view s)
	When using fmt >= 8, this is an alias for fmt::runtime. More...
template<typename T >
std::string fmt_floating_point(T x) requires(std std::string	fmt_floating_point (T x) requires(!(std
	Returns fmt::to_string(x) but always with at least one digit after the decimal point. More...
std::string	fmt_debug_string (std::string_view x)
	Returns fmt::("{:?}", x), i.e, using fmt's "debug string format"; see https://fmt.dev docs for the '?' presentation type for details. More...

Macro Definition Documentation

DRAKE_FMT8_CONST

#define DRAKE_FMT8_CONST   const

When using fmt >= 8, this is defined to be const to indicate that the fmt::formatter<T>::format(...) function should be object-const.

When using fmt < 8, the function signature was incorrect (lacking the const), so this macro will be empty.

DRAKE_FORMATTER_AS

#define DRAKE_FORMATTER_AS	(		TEMPLATE_ARGS,
			NAMESPACE,
			TYPE,
			ARG,
			EXPR
	)

Adds a fmt::formatter<NAMESPACE::TYPE> template specialization that formats the TYPE by delegating the formatting using a transformed expression, as if a conversion function like this were interposed during formatting:

template <TEMPLATE_ARGS>
auto format_as(const NAMESPACE::TYPE& ARG) {
  return EXPR;
}

For example, this declaration ...

DRAKE_FORMATTER_AS(, my_namespace, MyType, x, x.to_string())

... changes this code ...

MyType foo;
fmt::print(foo);

... to be equivalent to ...

MyType foo;
fmt::print(foo.to_string());

... allowing user to format my_namespace::MyType objects without manually adding the to_string call every time.

This provides a convenient mechanism to add formatters for classes that already have a to_string function, or classes that are just thin wrappers over simple types (ints, enums, etc.).

Always use this macro in the global namespace, and do not use a semicolon (;) afterward.

Parameters

TEMPLATE_ARGS	The optional first argument TEMPLATE_ARGS can be used in case the TYPE is templated, e.g., it might commonly be set to typename T. It should be left empty when the TYPE is not templated. In case TYPE has multiple template arguments, note that macros will fight with commas so you should use typename... Ts instead of writing them all out.
NAMESPACE	The namespace that encloses the TYPE being formatted. Cannot be empty. For nested namespaces, use intermediate colons, e.g., drake::common. Do not place leading colons on the NAMESPACE.
TYPE	The class name (or struct name, or enum name, etc.) being formatted. Do not place leading double-colons on the TYPE. If the type is templated, use the template arguments here, e.g., MyOptional<T> if TEMPLATE_ARGS was chosen as typename T.
ARG	A placeholder variable name to use for the value (i.e., object) being formatted within the EXPR expression.
EXPR	An expression to return from the format_as function; it can refer to the given ARG name which will be of type const TYPE& ARG. The evaluated expression can only ever throw exceptions that std::string's default allocator might throw (i.e., std::bad_alloc).

Note

In future versions of fmt (perhaps fmt >= 10) there might be an ADL format_as customization point with this feature built-in. If so, then we can update this macro to use that spelling, and eventually deprecate the macro once Drake drops support for earlier version of fmt.