.. image:: https://ci.appveyor.com/api/projects/status/ehjkiefde6gucy1v
:target: https://ci.appveyor.com/project/vitaut/fmt
-
-.. image:: https://badges.gitter.im/Join%20Chat.svg
- :alt: Join the chat at https://gitter.im/fmtlib/fmt
- :target: https://gitter.im/fmtlib/fmt
+
+.. image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/libfmt.svg
+ :alt: fmt is continuously fuzzed att oss-fuzz
+ :target: https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dlibfmt&can=1
+
+.. image:: https://img.shields.io/badge/stackoverflow-fmt-blue.svg
+ :alt: Ask questions at StackOverflow with the tag fmt
+ :target: https://stackoverflow.com/questions/tagged/fmt
**{fmt}** is an open-source formatting library for C++.
It can be used as a safe and fast alternative to (s)printf and iostreams.
-`Documentation <http://fmtlib.net/latest/>`__
+`Documentation <https://fmt.dev/latest/>`__
+
+Q&A: ask questions on `StackOverflow with the tag fmt <https://stackoverflow.com/questions/tagged/fmt>`_.
Features
--------
-* Replacement-based `format API <http://fmtlib.net/dev/api.html>`_ with
+* Replacement-based `format API <https://fmt.dev/dev/api.html>`_ with
positional arguments for localization.
-* `Format string syntax <http://fmtlib.net/dev/syntax.html>`_ similar to the one
- of `str.format <https://docs.python.org/2/library/stdtypes.html#str.format>`_
+* `Format string syntax <https://fmt.dev/dev/syntax.html>`_ similar to the one
+ of `str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
in Python.
* Safe `printf implementation
- <http://fmtlib.net/latest/api.html#printf-formatting>`_ including
+ <https://fmt.dev/latest/api.html#printf-formatting>`_ including
the POSIX extension for positional arguments.
-* Implementation of the ISO C++ standards proposal `P0645
- Text Formatting <http://fmtlib.net/Text%20Formatting.html>`__.
+* Implementation of `C++20 std::format <https://en.cppreference.com/w/cpp/utility/format>`__.
* Support for user-defined types.
* High performance: faster than common standard library implementations of
- `printf <http://en.cppreference.com/w/cpp/io/c/fprintf>`_ and
+ `printf <https://en.cppreference.com/w/cpp/io/c/fprintf>`_ and
iostreams. See `Speed tests`_ and `Fast integer to string conversion in C++
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
* Small code size both in terms of source code (the minimum configuration
consists of just three header files, ``core.h``, ``format.h`` and
``format-inl.h``) and compiled code. See `Compile time and code bloat`_.
* Reliability: the library has an extensive set of `unit tests
- <https://github.com/fmtlib/fmt/tree/master/test>`_.
+ <https://github.com/fmtlib/fmt/tree/master/test>`_ and is continuously fuzzed.
* Safety: the library is fully type safe, errors in format strings can be
reported at compile time, automatic memory management prevents buffer overflow
errors.
* Ease of use: small self-contained code base, no external dependencies,
- permissive BSD `license
+ permissive MIT `license
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
-* `Portability <http://fmtlib.net/latest/index.html#portability>`_ with
+* `Portability <https://fmt.dev/latest/index.html#portability>`_ with
consistent output across platforms and support for older compilers.
* Clean warning-free codebase even on high warning levels
(``-Wall -Wextra -pedantic``).
* Support for wide strings.
* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro.
-See the `documentation <http://fmtlib.net/latest/>`_ for more details.
+See the `documentation <https://fmt.dev/latest/>`_ for more details.
Examples
--------
.. code:: c++
// test.cc
- #define FMT_STRING_ALIAS 1
#include <fmt/format.h>
- std::string s = format(fmt("{2}"), 42);
+ std::string s = format(FMT_STRING("{2}"), 42);
.. code::
$ c++ -Iinclude -std=c++14 test.cc
...
test.cc:4:17: note: in instantiation of function template specialization 'fmt::v5::format<S, int>' requested here
- std::string s = format(fmt("{2}"), 42);
+ std::string s = format(FMT_STRING("{2}"), 42);
^
include/fmt/core.h:778:19: note: non-constexpr function 'on_error' cannot be used in a constant expression
ErrorHandler::on_error(message);
// access the string with to_string(buf) or buf.data()
Format objects of user-defined types via a simple `extension API
-<http://fmtlib.net/latest/api.html#formatting-user-defined-types>`_:
+<https://fmt.dev/latest/api.html#formatting-user-defined-types>`_:
.. code:: c++
template <>
struct fmt::formatter<date> {
- template <typename ParseContext>
- constexpr auto parse(ParseContext &ctx) { return ctx.begin(); }
+ constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
template <typename FormatContext>
- auto format(const date &d, FormatContext &ctx) {
+ auto format(const date& d, FormatContext& ctx) {
return format_to(ctx.out(), "{}-{}-{}", d.year, d.month, d.day);
}
};
// s == "The date is 2012-12-9"
Create your own functions similar to `format
-<http://fmtlib.net/latest/api.html#format>`_ and
-`print <http://fmtlib.net/latest/api.html#print>`_
+<https://fmt.dev/latest/api.html#format>`_ and
+`print <https://fmt.dev/latest/api.html#print>`_
which take arbitrary arguments (`godbolt <https://godbolt.org/g/MHjHVf>`_):
.. code:: c++
// Prints formatted error message.
- void vreport_error(const char *format, fmt::format_args args) {
+ void vreport_error(const char* format, fmt::format_args args) {
fmt::print("Error: ");
fmt::vprint(format, args);
}
template <typename... Args>
- void report_error(const char *format, const Args & ... args) {
+ void report_error(const char* format, const Args & ... args) {
vreport_error(format, fmt::make_format_args(args...));
}
================= ============= ===========
Library Method Run Time, s
================= ============= ===========
-libc printf 1.01
-libc++ std::ostream 3.04
-{fmt} 1632f72 fmt::print 0.86
-tinyformat 2.0.1 tfm::printf 3.23
-Boost Format 1.67 boost::format 7.98
+libc printf 1.04
+libc++ std::ostream 3.05
+{fmt} 6.1.1 fmt::print 0.75
+Boost Format 1.67 boost::format 7.24
Folly Format folly::format 2.23
================= ============= ===========
-{fmt} is the fastest of the benchmarked methods, ~17% faster than ``printf``.
+{fmt} is the fastest of the benchmarked methods, ~35% faster than ``printf``.
The above results were generated by building ``tinyformat_test.cpp`` on macOS
-10.14.3 with ``clang++ -O3 -DSPEED_TEST -DHAVE_FORMAT``, and taking the best of
+10.14.6 with ``clang++ -O3 -DSPEED_TEST -DHAVE_FORMAT``, and taking the best of
three runs. In the test, the format string ``"%0.10f:%04d:%+g:%s:%p:%c:%%\n"``
or equivalent is filled 2,000,000 times with output sent to ``/dev/null``; for
further details refer to the `source
<https://github.com/fmtlib/format-benchmark/blob/master/tinyformat_test.cpp>`_.
+{fmt} is 10x faster than ``std::ostringstream`` and ``sprintf`` on floating-point
+formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
+and as fast as `double-conversion <https://github.com/google/double-conversion>`_:
+
+.. image:: https://user-images.githubusercontent.com/576385/69767160-cdaca400-112f-11ea-9fc5-347c9f83caad.png
+ :target: https://fmt.dev/unknown_mac64_clang10.0.html
+
Compile time and code bloat
~~~~~~~~~~~~~~~~~~~~~~~~~~~
printf+string 16.4 29 26
iostreams 31.1 59 55
{fmt} 19.0 37 34
-tinyformat 44.0 103 97
Boost Format 91.9 226 203
Folly Format 115.7 101 88
============= =============== ==================== ==================
printf+string 16.0 33 30
iostreams 28.3 56 52
{fmt} 18.2 59 50
-tinyformat 32.6 88 82
Boost Format 54.1 365 303
Folly Format 79.9 445 430
============= =============== ==================== ==================
``libc``, ``lib(std)c++`` and ``libfmt`` are all linked as shared libraries to
-compare formatting function overhead only. Boost Format and tinyformat are
-header-only libraries so they don't provide any linkage options.
+compare formatting function overhead only. Boost Format is a
+header-only library so it doesn't provide any linkage options.
Running the tests
~~~~~~~~~~~~~~~~~
Please refer to `Building the library`__ for the instructions on how to build
the library and run the unit tests.
-__ http://fmtlib.net/latest/usage.html#building-the-library
+__ https://fmt.dev/latest/usage.html#building-the-library
Benchmarks reside in a separate repository,
`format-benchmarks <https://github.com/fmtlib/format-benchmark>`_,
Projects using this library
---------------------------
-* `0 A.D. <http://play0ad.com/>`_: A free, open-source, cross-platform real-time
- strategy game
+* `0 A.D. <https://play0ad.com/>`_: A free, open-source, cross-platform
+ real-time strategy game
* `AMPL/MP <https://github.com/ampl/mp>`_:
An open-source library for mathematical programming
* `Ceph <https://ceph.com/>`_: A scalable distributed storage system
+* `ccache <https://ccache.dev/>`_: A compiler cache
+
* `CUAUV <http://cuauv.org/>`_: Cornell University's autonomous underwater
vehicle
+* `Drake <https://drake.mit.edu/>`_: A planning, control, and analysis toolbox
+ for nonlinear dynamical systems (MIT)
+
+* `Envoy <https://lyft.github.io/envoy/>`_: C++ L7 proxy and communication bus
+ (Lyft)
+
+* `FiveM <https://fivem.net/>`_: a modification framework for GTA V
+
+* `Folly <https://github.com/facebook/folly>`_: Facebook open-source library
+
* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
Player vs Player Gaming Network with tweaks
-* `KBEngine <http://kbengine.org/>`_: An open-source MMOG server engine
+* `KBEngine <https://kbengine.org/>`_: An open-source MMOG server engine
-* `Keypirinha <http://keypirinha.com/>`_: A semantic launcher for Windows
+* `Keypirinha <https://keypirinha.com/>`_: A semantic launcher for Windows
* `Kodi <https://kodi.tv/>`_ (formerly xbmc): Home theater software
-* `Lifeline <https://github.com/peter-clark/lifeline>`_: A 2D game
+* `Knuth <https://kth.cash/>`_: High-performance Bitcoin full-node
-* `Drake <http://drake.mit.edu/>`_: A planning, control, and analysis toolbox
- for nonlinear dynamical systems (MIT)
+* `Microsoft Verona <https://github.com/microsoft/verona>`_: Research programming language for concurrent ownership
-* `Envoy <https://lyft.github.io/envoy/>`_: C++ L7 proxy and communication bus
- (Lyft)
-
-* `FiveM <https://fivem.net/>`_: a modification framework for GTA V
+* `MongoDB <https://mongodb.com/>`_: Distributed document database
* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: A small tool to
generate randomized datasets
-* `OpenSpace <http://openspaceproject.com/>`_: An open-source astrovisualization
- framework
+* `OpenSpace <https://openspaceproject.com/>`_: An open-source
+ astrovisualization framework
-* `PenUltima Online (POL) <http://www.polserver.com/>`_:
+* `PenUltima Online (POL) <https://www.polserver.com/>`_:
An MMO server, compatible with most Ultima Online clients
+* `PyTorch <https://github.com/pytorch/pytorch>`_: An open-source machine
+ learning library
+
* `quasardb <https://www.quasardb.net/>`_: A distributed, high-performance,
associative database
* `redis-cerberus <https://github.com/HunanTV/redis-cerberus>`_: A Redis cluster
proxy
+* `redpanda <https://vectorized.io/redpanda>`_: A 10x faster Kafka® replacement
+ for mission critical systems written in C++
+
* `rpclib <http://rpclib.net/>`_: A modern C++ msgpack-RPC server and client
library
-* `Saddy <https://github.com/mamontov-cpp/saddy-graphics-engine-2d>`_:
- Small crossplatform 2D graphic engine
-
-* `Salesforce Analytics Cloud <http://www.salesforce.com/analytics-cloud/overview/>`_:
+* `Salesforce Analytics Cloud
+ <https://www.salesforce.com/analytics-cloud/overview/>`_:
Business intelligence software
-* `Scylla <http://www.scylladb.com/>`_: A Cassandra-compatible NoSQL data store
+* `Scylla <https://www.scylladb.com/>`_: A Cassandra-compatible NoSQL data store
that can handle 1 million transactions per second on a single server
* `Seastar <http://www.seastar-project.org/>`_: An advanced, open-source C++
* `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: Open-source
MMORPG framework
-`More... <https://github.com/search?q=cppformat&type=Code>`_
+* `Windows Terminal <https://github.com/microsoft/terminal>`_: The new Windows
+ Terminal
+
+`More... <https://github.com/search?q=fmtlib&type=Code>`_
If you are aware of other projects using this library, please let me know
by `email <mailto:victor.zverovich@gmail.com>`_ or by submitting an
being a part of the C standard library. The main drawback is that it
doesn't support user-defined types. ``printf`` also has safety issues although
they are somewhat mitigated with `__attribute__ ((format (printf, ...))
-<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
+<https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
There is a POSIX extension that adds positional arguments required for
`i18n <https://en.wikipedia.org/wiki/Internationalization_and_localization>`_
to ``printf`` but it is not a part of C99 and may not be available on some
It is also quite big and has a heavy dependency, STLSoft, which might be
too restrictive for using it in some projects.
-Loki SafeFormat
-~~~~~~~~~~~~~~~
-
-SafeFormat is a formatting library which uses ``printf``-like format strings and
-is type safe. It doesn't support user-defined types or positional arguments and
-makes unconventional use of ``operator()`` for passing format arguments.
-
-Tinyformat
-~~~~~~~~~~
-
-This library supports ``printf``-like format strings and is very small .
-It doesn't support positional arguments and wrapping it in C++98 is somewhat
-difficult. Tinyformat relies on iostreams which limits its performance.
-
Boost Spirit.Karma
~~~~~~~~~~~~~~~~~~
License
-------
-{fmt} is distributed under the BSD `license
+{fmt} is distributed under the MIT `license
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.
The `Format String Syntax
-<http://fmtlib.net/latest/syntax.html>`_
+<https://fmt.dev/latest/syntax.html>`_
section in the documentation is based on the one from Python `string module
documentation <https://docs.python.org/3/library/string.html#module-string>`_
adapted for the current library. For this reason the documentation is
since it had some influence on tinyformat.
Some ideas used in the implementation are borrowed from `Loki
<http://loki-lib.sourceforge.net/>`_ SafeFormat and `Diagnostic API
-<http://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`_ in
-`Clang <http://clang.llvm.org/>`_.
+<https://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`_ in
+`Clang <https://clang.llvm.org/>`_.
Format string syntax and the documentation are based on Python's `str.format
-<http://docs.python.org/2/library/stdtypes.html#str.format>`_.
+<https://docs.python.org/3/library/stdtypes.html#str.format>`_.
Thanks `Doug Turnbull <https://github.com/softwaredoug>`_ for his valuable
comments and contribution to the design of the type-safe API and
`Gregory Czajkowski <https://github.com/gcflymoto>`_ for implementing binary
projects / ceph.git / blobdiff