mirror of
https://github.com/fmtlib/fmt.git
synced 2024-11-08 11:33:46 +00:00
9c56a8ce5c
If a base class can be formatted, it is assumed that the hierarchy can be formatted from the base class. The idiom is not uncommon with ostreams.
310 lines
8.8 KiB
ReStructuredText
310 lines
8.8 KiB
ReStructuredText
.. _string-formatting-api:
|
|
|
|
*************
|
|
API Reference
|
|
*************
|
|
|
|
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.
|
|
|
|
Format API
|
|
==========
|
|
|
|
The following functions defined in ``fmt/format.h`` use :ref:`format string
|
|
syntax <syntax>` similar to the one used by Python's `str.format
|
|
<http://docs.python.org/3/library/stdtypes.html#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
|
|
<https://github.com/fmtlib/fmt/blob/master/README.rst#speed-tests>`_ is close
|
|
to that of glibc's ``printf`` and better than the performance of IOStreams.
|
|
For even better speed use the `write API`_.
|
|
|
|
.. _format:
|
|
|
|
.. doxygenfunction:: format(CStringRef, ArgList)
|
|
|
|
.. doxygenfunction:: operator""_format(const char *, std::size_t)
|
|
|
|
.. _print:
|
|
|
|
.. doxygenfunction:: print(CStringRef, ArgList)
|
|
|
|
.. doxygenfunction:: print(std::FILE *, CStringRef, ArgList)
|
|
|
|
.. doxygenclass:: fmt::BasicFormatter
|
|
:members:
|
|
|
|
Date and time formatting
|
|
------------------------
|
|
|
|
The library supports `strftime
|
|
<http://en.cppreference.com/w/cpp/chrono/c/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 <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
|
|
|
|
Formatting user-defined types
|
|
-----------------------------
|
|
|
|
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 technique can also be used for formatting class hierarchies::
|
|
|
|
namespace local {
|
|
struct Parent {
|
|
Parent(int p) : p(p) {}
|
|
virtual void write(fmt::Writer &w) const {
|
|
w.write("Parent : p={}", p);
|
|
}
|
|
int p;
|
|
};
|
|
|
|
struct Child : Parent {
|
|
Child(int c, int p) : Parent(p), c(c) {}
|
|
virtual void write(fmt::Writer &w) const {
|
|
w.write("Child c={} : ", c);
|
|
Parent::write(w);
|
|
}
|
|
int c;
|
|
};
|
|
|
|
void format_arg(fmt::BasicFormatter<char> &f,
|
|
const char *&format_str, const Parent &p) {
|
|
p.write(f.writer());
|
|
}
|
|
}
|
|
Local::Child c(1,2);
|
|
Local::Parent &p = c;
|
|
fmt::print("via ref to base: {}\n", p);
|
|
fmt::print("direct to child: {}\n", c);
|
|
|
|
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.
|
|
|
|
``std::ostream`` support
|
|
------------------------
|
|
|
|
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)
|
|
|
|
Argument formatters
|
|
-------------------
|
|
|
|
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:
|
|
|
|
Printf formatting
|
|
-----------------
|
|
|
|
The header ``fmt/printf.h`` provides ``printf``-like formatting functionality.
|
|
The following functions use `printf format string syntax
|
|
<http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html>`_ 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:
|
|
|
|
Write API
|
|
=========
|
|
|
|
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:
|
|
|
|
.. doxygenclass:: fmt::BasicContainerWriter
|
|
:members:
|
|
|
|
.. doxygenfunction:: bin(int)
|
|
|
|
.. doxygenfunction:: oct(int)
|
|
|
|
.. doxygenfunction:: hex(int)
|
|
|
|
.. doxygenfunction:: hexu(int)
|
|
|
|
.. doxygenfunction:: pad(int, unsigned, Char)
|
|
|
|
Utilities
|
|
=========
|
|
|
|
.. 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:
|
|
|
|
System errors
|
|
=============
|
|
|
|
.. doxygenclass:: fmt::SystemError
|
|
:members:
|
|
|
|
.. doxygenfunction:: fmt::format_system_error
|
|
|
|
.. doxygenclass:: fmt::WindowsError
|
|
:members:
|
|
|
|
.. _formatstrings:
|
|
|
|
Custom allocators
|
|
=================
|
|
|
|
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)
|