All functions and classes provided by the fmt library reside
in namespace fmt and macros have prefix FMT_. For brevity the
namespace is usually omitted in examples.
The following functions use :ref:`format string syntax <syntax>` similar to the one used by Python's str.format function. They take format_str and args as arguments.
format_str is a format string that contains literal text and replacement
fields surrounded by braces {}. The fields are replaced with formatted
arguments in the resulting string.
args is an argument list representing arbitrary arguments.
The performance of the format API is close
to that of glibc's printf and better than the performance of IOStreams.
For even better speed use the write API.
.. doxygenfunction:: format(CStringRef, ArgList)
.. doxygenfunction:: operator""_format(const char *, std::size_t)
.. doxygenfunction:: print(CStringRef, ArgList)
.. doxygenfunction:: print(std::FILE *, CStringRef, ArgList)
.. doxygenclass:: fmt::BasicFormatter :members:
The library supports strftime-like date and time formatting:
#include "fmt/time.h"
std::time_t t = std::time(nullptr);
// Prints "The date is 2016-04-29." (with the current date)
fmt::print("The date is {:%Y-%m-%d}.", *std::localtime(&t));
The format string syntax is described in the documentation of strftime.
A custom format_arg function may be implemented and used to format any
user-defined type. That is how date and time formatting described in the
previous section is implemented in :file:`fmt/time.h`. The following example
shows how to implement custom formatting for a user-defined structure.
struct MyStruct { double a, b; };
void format_arg(fmt::BasicFormatter<char> &f,
const char *&format_str, const MyStruct &s) {
f.writer().write("[MyStruct: a={:.1f}, b={:.2f}]", s.a, s.b);
}
MyStruct m = { 1, 2 };
std::string s = fmt::format("m={}", n);
// s == "m=[MyStruct: a=1.0, b=2.00]"
Note in the example above the format_arg function ignores the contents of
format_str so the type will always be formatted as specified. See
format_arg in :file:`fmt/time.h` for an advanced example of how to use
the format_str argument to customize the formatted output.
This section shows how to define a custom format function for a user-defined
type. The next section describes how to get fmt to use a conventional stream
output operator<< when one is defined for a user-defined type.
The header fmt/ostream.h provides std::ostream support including
formatting of user-defined types that have overloaded operator<<:
#include "fmt/ostream.h"
class Date {
int year_, month_, day_;
public:
Date(int year, int month, int day): year_(year), month_(month), day_(day) {}
friend std::ostream &operator<<(std::ostream &os, const Date &d) {
return os << d.year_ << '-' << d.month_ << '-' << d.day_;
}
};
std::string s = fmt::format("The date is {}", Date(2012, 12, 9));
// s == "The date is 2012-12-9"
.. doxygenfunction:: print(std::ostream&, CStringRef, ArgList)
It is possible to change the way arguments are formatted by providing a custom argument formatter class:
// A custom argument formatter that formats negative integers as unsigned
// with the ``x`` format specifier.
class CustomArgFormatter :
public fmt::BasicArgFormatter<CustomArgFormatter, char> {
public:
CustomArgFormatter(fmt::BasicFormatter<char, CustomArgFormatter> &f,
fmt::FormatSpec &s, const char *fmt)
: fmt::BasicArgFormatter<CustomArgFormatter, char>(f, s, fmt) {}
void visit_int(int value) {
if (spec().type() == 'x')
visit_uint(value); // convert to unsigned and format
else
fmt::BasicArgFormatter<CustomArgFormatter, char>::visit_int(value);
}
};
std::string custom_format(const char *format_str, fmt::ArgList args) {
fmt::MemoryWriter writer;
// Pass custom argument formatter as a template arg to BasicFormatter.
fmt::BasicFormatter<char, CustomArgFormatter> formatter(args, writer);
formatter.format(format_str);
return writer.str();
}
FMT_VARIADIC(std::string, custom_format, const char *)
std::string s = custom_format("{:x}", -42); // s == "ffffffd6"
.. doxygenclass:: fmt::ArgVisitor :members:
.. doxygenclass:: fmt::BasicArgFormatter :members:
.. doxygenclass:: fmt::ArgFormatter :members:
The header fmt/printf.h provides printf-like formatting functionality.
The following functions use printf format string syntax with
the POSIX extension for positional arguments. Unlike their standard
counterparts, the fmt functions are type-safe and throw an exception if an
argument type doesn't match its format specification.
.. doxygenfunction:: printf(CStringRef, ArgList)
.. doxygenfunction:: fprintf(std::FILE *, CStringRef, ArgList)
.. doxygenfunction:: fprintf(std::ostream&, CStringRef, ArgList)
.. doxygenfunction:: sprintf(CStringRef, ArgList)
.. doxygenclass:: fmt::PrintfFormatter :members:
.. doxygenclass:: fmt::BasicPrintfArgFormatter :members:
.. doxygenclass:: fmt::PrintfArgFormatter :members:
The write API provides classes for writing formatted data into character streams. It is usually faster than the format API but, as IOStreams, may result in larger compiled code size. The main writer class is ~fmt::BasicMemoryWriter which stores its output in a memory buffer and provides direct access to it. It is possible to create custom writers that store output elsewhere by subclassing ~fmt::BasicWriter.
.. doxygenclass:: fmt::BasicWriter :members:
.. doxygenclass:: fmt::BasicMemoryWriter :members:
.. doxygenclass:: fmt::BasicArrayWriter :members:
.. doxygenclass:: fmt::BasicStringWriter :members:
.. doxygenfunction:: bin(int)
.. doxygenfunction:: oct(int)
.. doxygenfunction:: hex(int)
.. doxygenfunction:: hexu(int)
.. doxygenfunction:: pad(int, unsigned, Char)
.. doxygenfunction:: fmt::arg(StringRef, const T&)
.. doxygenfunction:: operator""_a(const char *, std::size_t)
.. doxygendefine:: FMT_CAPTURE
.. doxygendefine:: FMT_VARIADIC
.. doxygenclass:: fmt::ArgList :members:
.. doxygenfunction:: fmt::to_string(const T&)
.. doxygenclass:: fmt::BasicStringRef :members:
.. doxygenclass:: fmt::BasicCStringRef :members:
.. doxygenclass:: fmt::Buffer :protected-members: :members:
.. doxygenclass:: fmt::SystemError :members:
.. doxygenfunction:: fmt::format_system_error
.. doxygenclass:: fmt::WindowsError :members:
The fmt library supports custom dynamic memory allocators. A custom allocator class can be specified as a template argument to :class:`fmt::BasicMemoryWriter`:
typedef fmt::BasicMemoryWriter<char, CustomAllocator> CustomMemoryWriter;
It is also possible to write a formatting function that uses a custom allocator:
typedef std::basic_string<char, std::char_traits<char>, CustomAllocator>
CustomString;
CustomString format(CustomAllocator alloc, fmt::CStringRef format_str,
fmt::ArgList args) {
CustomMemoryWriter writer(alloc);
writer.write(format_str, args);
return CustomString(writer.data(), writer.size(), alloc);
}
FMT_VARIADIC(CustomString, format, CustomAllocator, fmt::CStringRef)