fmt/doc/api.rst

230 lines
6.4 KiB
ReStructuredText
Raw Normal View History

2014-10-10 15:40:35 +00:00
.. _string-formatting-api:
*************
API Reference
*************
2016-04-27 15:35:59 +00:00
All functions and classes provided by the fmt library reside
2014-10-10 15:40:35 +00:00
in namespace ``fmt`` and macros have prefix ``FMT_``. For brevity the
namespace is usually omitted in examples.
2015-12-18 15:16:40 +00:00
Format API
==========
2014-10-10 15:40:35 +00:00
The following functions 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.
2016-05-10 14:29:31 +00:00
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`_.
2014-10-10 15:40:35 +00:00
.. _format:
2015-06-26 16:09:23 +00:00
.. doxygenfunction:: format(CStringRef, ArgList)
2014-10-10 15:40:35 +00:00
.. doxygenfunction:: operator""_format(const char *, std::size_t)
2014-10-10 15:40:35 +00:00
.. _print:
2015-06-26 16:09:23 +00:00
.. doxygenfunction:: print(CStringRef, ArgList)
2014-10-10 15:40:35 +00:00
2015-06-26 16:09:23 +00:00
.. doxygenfunction:: print(std::FILE *, CStringRef, ArgList)
2014-10-10 15:40:35 +00:00
2015-12-18 15:16:40 +00:00
.. doxygenclass:: fmt::BasicFormatter
:members:
2015-12-18 15:16:40 +00:00
Date and time formatting
------------------------
2016-04-29 14:02:37 +00:00
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
2016-04-29 14:02:37 +00:00
`strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
2016-05-07 16:09:33 +00:00
``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)
.. doxygenfunction:: fprintf(std::ostream&, CStringRef, ArgList)
2016-04-20 14:16:52 +00:00
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:
2016-04-20 14:16:52 +00:00
.. doxygenclass:: fmt::BasicArgFormatter
:members:
.. doxygenclass:: fmt::ArgFormatter
:members:
2014-10-10 15:40:35 +00:00
Printf formatting functions
2015-12-18 15:16:40 +00:00
---------------------------
2014-10-10 15:40:35 +00:00
The following functions use `printf format string syntax
<http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html>`_ with
a POSIX extension for positional arguments.
2015-06-26 16:09:23 +00:00
.. doxygenfunction:: printf(CStringRef, ArgList)
2014-10-10 15:40:35 +00:00
.. doxygenfunction:: fprintf(std::FILE *, CStringRef, ArgList)
2015-06-26 16:09:23 +00:00
.. doxygenfunction:: sprintf(CStringRef, ArgList)
2014-10-10 15:40:35 +00:00
Write API
=========
2016-05-10 14:29:31 +00:00
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
2016-05-10 18:07:53 +00:00
direct access to it. It is possible to create custom writers that
2016-05-10 14:29:31 +00:00
store output elsewhere by subclassing `~fmt::BasicWriter`.
2014-10-10 15:40:35 +00:00
.. doxygenclass:: fmt::BasicWriter
:members:
.. doxygenclass:: fmt::BasicMemoryWriter
:members:
2015-03-02 02:10:09 +00:00
.. doxygenclass:: fmt::BasicArrayWriter
:members:
2016-04-11 13:32:24 +00:00
.. doxygenfunction:: bin(int)
2014-10-10 15:40:35 +00:00
2016-04-11 13:32:24 +00:00
.. doxygenfunction:: oct(int)
2014-10-10 15:40:35 +00:00
2016-04-11 13:32:24 +00:00
.. doxygenfunction:: hex(int)
2014-10-10 15:40:35 +00:00
2016-04-11 13:32:24 +00:00
.. doxygenfunction:: hexu(int)
2014-10-10 15:40:35 +00:00
2015-05-20 01:04:32 +00:00
.. doxygenfunction:: pad(int, unsigned, Char)
2014-10-10 15:40:35 +00:00
Utilities
=========
2015-06-10 01:32:59 +00:00
.. doxygenfunction:: fmt::arg(StringRef, const T&)
.. doxygenfunction:: operator""_a(const char *, std::size_t)
2015-06-10 01:32:59 +00:00
.. doxygendefine:: FMT_CAPTURE
2014-10-10 15:40:35 +00:00
.. doxygendefine:: FMT_VARIADIC
.. doxygenclass:: fmt::ArgList
:members:
2016-05-19 02:54:52 +00:00
.. doxygenfunction:: fmt::to_string(const T&)
2014-10-10 15:40:35 +00:00
.. doxygenclass:: fmt::BasicStringRef
:members:
2015-06-26 16:09:23 +00:00
.. doxygenclass:: fmt::BasicCStringRef
:members:
2015-03-20 13:42:55 +00:00
.. doxygenclass:: fmt::Buffer
2015-03-20 13:46:39 +00:00
:protected-members:
2015-03-20 13:42:55 +00:00
:members:
2016-04-20 14:44:37 +00:00
System errors
2014-10-10 15:40:35 +00:00
=============
.. doxygenclass:: fmt::SystemError
:members:
.. doxygenfunction:: fmt::format_system_error
2014-10-10 15:40:35 +00:00
.. doxygenclass:: fmt::WindowsError
:members:
.. _formatstrings:
Custom allocators
=================
2016-04-27 15:35:59 +00:00
The fmt library supports custom dynamic memory allocators.
2014-10-10 15:40:35 +00:00
A custom allocator class can be specified as a template argument to
2014-12-18 16:36:53 +00:00
:class:`fmt::BasicMemoryWriter`::
2014-10-10 15:40:35 +00:00
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;
2015-06-26 16:09:23 +00:00
CustomString format(CustomAllocator alloc, fmt::CStringRef format_str,
2014-10-10 15:40:35 +00:00
fmt::ArgList args) {
CustomMemoryWriter writer(alloc);
writer.write(format_str, args);
return CustomString(writer.data(), writer.size(), alloc);
}
2015-06-26 16:09:23 +00:00
FMT_VARIADIC(CustomString, format, CustomAllocator, fmt::CStringRef)