mirror of
https://github.com/fmtlib/fmt.git
synced 2024-12-24 12:14:26 +00:00
Update docs
This commit is contained in:
parent
a1d187113b
commit
9facc119a6
259
doc/api.rst
259
doc/api.rst
@ -4,14 +4,29 @@
|
|||||||
API Reference
|
API Reference
|
||||||
*************
|
*************
|
||||||
|
|
||||||
All functions and classes provided by the {fmt} library reside in namespace
|
The {fmt} library API consists of the following parts:
|
||||||
``fmt`` and macros have prefix ``FMT_``.
|
|
||||||
|
|
||||||
Format API
|
* :ref:`fmt/core.h <core-api>`: the core API providing argument handling
|
||||||
==========
|
facilities and a lightweight subset of formatting functions
|
||||||
|
* :ref:`fmt/format.h <format-api>`: the full format API providing compile-time
|
||||||
|
format string checks, output iterator and user-defined type support
|
||||||
|
* :ref:`fmt/time.h <time-api>`: date and time formatting
|
||||||
|
* :ref:`fmt/ostream.h <ostream-api>`: ``std::ostream`` support
|
||||||
|
* :ref:`fmt/printf.h <printf-api>`: ``printf`` formatting
|
||||||
|
|
||||||
The following functions defined in ``fmt/core.h`` use :ref:`format string
|
All functions and types provided by the library reside in namespace ``fmt`` and
|
||||||
syntax <syntax>` similar to that of Python's `str.format
|
macros have prefix ``FMT_`` or ``fmt``.
|
||||||
|
|
||||||
|
.. _core-api:
|
||||||
|
|
||||||
|
Core API
|
||||||
|
========
|
||||||
|
|
||||||
|
``fmt/core.h`` defines the core API which provides argument handling facilities
|
||||||
|
and a lightweight subset of formatting functions.
|
||||||
|
|
||||||
|
The following functions use :ref:`format string syntax <syntax>`
|
||||||
|
imilar to that of Python's `str.format
|
||||||
<http://docs.python.org/3/library/stdtypes.html#str.format>`_.
|
<http://docs.python.org/3/library/stdtypes.html#str.format>`_.
|
||||||
They take *format_str* and *args* as arguments.
|
They take *format_str* and *args* as arguments.
|
||||||
|
|
||||||
@ -21,35 +36,52 @@ arguments in the resulting string.
|
|||||||
|
|
||||||
*args* is an argument list representing objects to be formatted.
|
*args* is an argument list representing objects to be formatted.
|
||||||
|
|
||||||
The `performance of the formating functions
|
|
||||||
<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.
|
|
||||||
|
|
||||||
.. _format:
|
.. _format:
|
||||||
|
|
||||||
.. doxygenfunction:: format(string_view, const Args&...)
|
.. doxygenfunction:: format(string_view, const Args&...)
|
||||||
|
.. doxygenfunction:: vformat(string_view, format_args)
|
||||||
|
|
||||||
.. _print:
|
.. _print:
|
||||||
|
|
||||||
.. doxygenfunction:: print(string_view, const Args&...)
|
.. doxygenfunction:: print(string_view, const Args&...)
|
||||||
|
.. doxygenfunction:: vprint(string_view, format_args)
|
||||||
|
|
||||||
.. doxygenfunction:: print(std::FILE *, string_view, const Args&...)
|
.. doxygenfunction:: print(std::FILE *, string_view, const Args&...)
|
||||||
|
.. doxygenfunction:: vprint(std::FILE *, string_view, format_args)
|
||||||
|
|
||||||
Date and time formatting
|
.. _format-api:
|
||||||
------------------------
|
|
||||||
|
|
||||||
The library supports `strftime
|
Named arguments
|
||||||
<http://en.cppreference.com/w/cpp/chrono/c/strftime>`_-like date and time
|
---------------
|
||||||
formatting::
|
|
||||||
|
|
||||||
#include "fmt/time.h"
|
.. doxygenfunction:: fmt::arg(string_view, const T&)
|
||||||
|
|
||||||
std::time_t t = std::time(nullptr);
|
Argument lists
|
||||||
// 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
|
.. doxygenclass:: fmt::basic_format_args
|
||||||
`strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
|
:members:
|
||||||
|
|
||||||
|
.. doxygenstruct:: fmt::format_args
|
||||||
|
|
||||||
|
.. doxygenfunction:: fmt::make_args(const Args&...)
|
||||||
|
|
||||||
|
Compatibility
|
||||||
|
-------------
|
||||||
|
|
||||||
|
.. doxygenclass:: fmt::basic_string_view
|
||||||
|
:members:
|
||||||
|
|
||||||
|
Format API
|
||||||
|
==========
|
||||||
|
|
||||||
|
``fmt/format.h`` defines the full format API providing compile-time format
|
||||||
|
string checks, output iterator and user-defined type support.
|
||||||
|
|
||||||
|
Compile-time format string checks
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
.. doxygendefine:: fmt
|
||||||
|
|
||||||
Formatting user-defined types
|
Formatting user-defined types
|
||||||
-----------------------------
|
-----------------------------
|
||||||
@ -57,6 +89,8 @@ Formatting user-defined types
|
|||||||
To make a user-defined type formattable, specialize the ``formatter<T>`` struct
|
To make a user-defined type formattable, specialize the ``formatter<T>`` struct
|
||||||
template and implement ``parse`` and ``format`` methods::
|
template and implement ``parse`` and ``format`` methods::
|
||||||
|
|
||||||
|
#include <fmt/format.h>
|
||||||
|
|
||||||
struct point { double x, y; };
|
struct point { double x, y; };
|
||||||
|
|
||||||
namespace fmt {
|
namespace fmt {
|
||||||
@ -88,28 +122,10 @@ 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
|
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.
|
output ``operator<<`` when one is defined for a user-defined type.
|
||||||
|
|
||||||
``std::ostream`` support
|
Output iterator support
|
||||||
------------------------
|
-----------------------
|
||||||
|
|
||||||
The header ``fmt/ostream.h`` provides ``std::ostream`` support including
|
.. doxygenfunction:: fmt::format_to(OutputIt, string_view, const Args&...)
|
||||||
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&, string_view, const Args&...)
|
|
||||||
|
|
||||||
Literal-based API
|
Literal-based API
|
||||||
-----------------
|
-----------------
|
||||||
@ -120,6 +136,57 @@ The following user-defined literals are defined in ``fmt/format.h``.
|
|||||||
|
|
||||||
.. doxygenfunction:: operator""_a(const char *, std::size_t)
|
.. doxygenfunction:: operator""_a(const char *, std::size_t)
|
||||||
|
|
||||||
|
Utilities
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. doxygenfunction:: fmt::to_string(const T&)
|
||||||
|
|
||||||
|
.. doxygenclass:: fmt::basic_memory_buffer
|
||||||
|
:protected-members:
|
||||||
|
:members:
|
||||||
|
|
||||||
|
System errors
|
||||||
|
-------------
|
||||||
|
|
||||||
|
.. doxygenclass:: fmt::system_error
|
||||||
|
:members:
|
||||||
|
|
||||||
|
.. doxygenfunction:: fmt::format_system_error
|
||||||
|
|
||||||
|
.. doxygenclass:: fmt::windows_error
|
||||||
|
: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::basic_memory_buffer`::
|
||||||
|
|
||||||
|
using custom_memory_buffer =
|
||||||
|
fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>;
|
||||||
|
|
||||||
|
It is also possible to write a formatting function that uses a custom
|
||||||
|
allocator::
|
||||||
|
|
||||||
|
using custom_string =
|
||||||
|
std::basic_string<char, std::char_traits<char>, custom_allocator>;
|
||||||
|
|
||||||
|
custom_string vformat(custom_allocator alloc, fmt::string_view format_str,
|
||||||
|
fmt::format_args args) {
|
||||||
|
custom_memory_buffer buf(alloc);
|
||||||
|
fmt::vformat_to(buf, format_str, args);
|
||||||
|
return custom_string(buf.data(), buf.size(), alloc);
|
||||||
|
}
|
||||||
|
|
||||||
|
template <typename ...Args>
|
||||||
|
inline custom_string format(custom_allocator alloc,
|
||||||
|
fmt::string_view format_str,
|
||||||
|
const Args & ... args) {
|
||||||
|
return vformat(alloc, format_str, fmt::make_args(args...));
|
||||||
|
}
|
||||||
Custom formatting of built-in types
|
Custom formatting of built-in types
|
||||||
-----------------------------------
|
-----------------------------------
|
||||||
|
|
||||||
@ -170,8 +237,53 @@ custom argument formatter class::
|
|||||||
.. doxygenclass:: fmt::arg_formatter
|
.. doxygenclass:: fmt::arg_formatter
|
||||||
:members:
|
:members:
|
||||||
|
|
||||||
Printf formatting
|
.. _time-api:
|
||||||
-----------------
|
|
||||||
|
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>`_.
|
||||||
|
|
||||||
|
.. _ostream-api:
|
||||||
|
|
||||||
|
``std::ostream`` support
|
||||||
|
========================
|
||||||
|
|
||||||
|
``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&, string_view, const Args&...)
|
||||||
|
|
||||||
|
.. _printf-api:
|
||||||
|
|
||||||
|
``printf`` formatting
|
||||||
|
=====================
|
||||||
|
|
||||||
The header ``fmt/printf.h`` provides ``printf``-like formatting functionality.
|
The header ``fmt/printf.h`` provides ``printf``-like formatting functionality.
|
||||||
The following functions use `printf format string syntax
|
The following functions use `printf format string syntax
|
||||||
@ -220,62 +332,3 @@ store output elsewhere by subclassing `~fmt::BasicWriter`.
|
|||||||
|
|
||||||
.. doxygenfunction:: pad(int, unsigned, Char)
|
.. doxygenfunction:: pad(int, unsigned, Char)
|
||||||
|
|
||||||
Utilities
|
|
||||||
=========
|
|
||||||
|
|
||||||
.. doxygenfunction:: fmt::arg(string_view, const T&)
|
|
||||||
|
|
||||||
.. doxygenclass:: fmt::basic_format_args
|
|
||||||
:members:
|
|
||||||
|
|
||||||
.. doxygenfunction:: fmt::to_string(const T&)
|
|
||||||
|
|
||||||
.. doxygenclass:: fmt::basic_string_view
|
|
||||||
:members:
|
|
||||||
|
|
||||||
.. doxygenclass:: fmt::basic_memory_buffer
|
|
||||||
:protected-members:
|
|
||||||
:members:
|
|
||||||
|
|
||||||
System errors
|
|
||||||
=============
|
|
||||||
|
|
||||||
.. doxygenclass:: fmt::system_error
|
|
||||||
:members:
|
|
||||||
|
|
||||||
.. doxygenfunction:: fmt::format_system_error
|
|
||||||
|
|
||||||
.. doxygenclass:: fmt::windows_error
|
|
||||||
: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::basic_memory_buffer`::
|
|
||||||
|
|
||||||
using custom_memory_buffer =
|
|
||||||
fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>;
|
|
||||||
|
|
||||||
It is also possible to write a formatting function that uses a custom
|
|
||||||
allocator::
|
|
||||||
|
|
||||||
using custom_string =
|
|
||||||
std::basic_string<char, std::char_traits<char>, custom_allocator>;
|
|
||||||
|
|
||||||
custom_string vformat(custom_allocator alloc, fmt::string_view format_str,
|
|
||||||
fmt::format_args args) {
|
|
||||||
custom_memory_buffer buf(alloc);
|
|
||||||
fmt::vformat_to(buf, format_str, args);
|
|
||||||
return custom_string(buf.data(), buf.size(), alloc);
|
|
||||||
}
|
|
||||||
|
|
||||||
template <typename ...Args>
|
|
||||||
inline custom_string format(custom_allocator alloc,
|
|
||||||
fmt::string_view format_str,
|
|
||||||
const Args & ... args) {
|
|
||||||
return vformat(alloc, format_str, fmt::make_args(args...));
|
|
||||||
}
|
|
||||||
|
@ -1069,7 +1069,8 @@ class basic_format_args {
|
|||||||
}
|
}
|
||||||
};
|
};
|
||||||
|
|
||||||
// This is a separate type rather than a typedef to make symbols readable.
|
/** An alias to ``basic_format_args<context>``. */
|
||||||
|
// It is a separate type rather than a typedef to make symbols readable.
|
||||||
struct format_args: basic_format_args<context> {
|
struct format_args: basic_format_args<context> {
|
||||||
template <typename ...Args>
|
template <typename ...Args>
|
||||||
format_args(Args && ... arg)
|
format_args(Args && ... arg)
|
||||||
@ -1179,7 +1180,7 @@ std::wstring vformat(wstring_view format_str, wformat_args args);
|
|||||||
|
|
||||||
**Example**::
|
**Example**::
|
||||||
|
|
||||||
#include "fmt/core.h"
|
#include <fmt/core.h>
|
||||||
std::string message = fmt::format("The answer is {}", 42);
|
std::string message = fmt::format("The answer is {}", 42);
|
||||||
\endrst
|
\endrst
|
||||||
*/
|
*/
|
||||||
|
@ -3315,7 +3315,7 @@ auto join(const Range &range, wstring_view sep)
|
|||||||
|
|
||||||
**Example**::
|
**Example**::
|
||||||
|
|
||||||
#include "fmt/format.h"
|
#include <fmt/format.h>
|
||||||
|
|
||||||
std::string answer = fmt::to_string(42);
|
std::string answer = fmt::to_string(42);
|
||||||
\endrst
|
\endrst
|
||||||
@ -3528,6 +3528,16 @@ operator"" _a(const wchar_t *s, std::size_t) { return {s}; }
|
|||||||
}()
|
}()
|
||||||
|
|
||||||
#ifndef FMT_NO_FMT_STRING_ALIAS
|
#ifndef FMT_NO_FMT_STRING_ALIAS
|
||||||
|
/**
|
||||||
|
\rst
|
||||||
|
Constructs a compile-time format string.
|
||||||
|
|
||||||
|
**Example**::
|
||||||
|
|
||||||
|
#include <fmt/format.h>
|
||||||
|
std::string s = fmt::format(fmt("{:d}"), "foo"); // fails to compile
|
||||||
|
\endrst
|
||||||
|
*/
|
||||||
# define fmt(s) FMT_STRING(s)
|
# define fmt(s) FMT_STRING(s)
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user