2014-04-18 04:17:56 +00:00
|
|
|
|
C++ Format
|
|
|
|
|
==========
|
2012-12-07 16:26:46 +00:00
|
|
|
|
|
2014-04-18 04:17:56 +00:00
|
|
|
|
.. image:: https://travis-ci.org/cppformat/cppformat.png?branch=master
|
|
|
|
|
:target: https://travis-ci.org/cppformat/cppformat
|
2014-04-15 06:19:38 +00:00
|
|
|
|
|
2014-04-25 15:57:34 +00:00
|
|
|
|
.. image:: https://ci.appveyor.com/api/projects/status/qk0bhyhqp1ekpat8
|
|
|
|
|
:target: https://ci.appveyor.com/project/vitaut/cppformat
|
2014-04-25 15:21:26 +00:00
|
|
|
|
|
2014-11-04 15:42:56 +00:00
|
|
|
|
.. image:: https://readthedocs.org/projects/cppformat/badge/?version=stable
|
2014-11-04 15:44:07 +00:00
|
|
|
|
:target: http://cppformat.readthedocs.org/en/stable/
|
2014-11-04 15:42:56 +00:00
|
|
|
|
:alt: Documentation Status
|
2015-02-06 14:19:30 +00:00
|
|
|
|
|
|
|
|
|
.. image:: https://webapi.biicode.com/v1/badges/vitaut/vitaut/cppformat/master
|
|
|
|
|
:target: https://www.biicode.com/vitaut/cppformat
|
2014-11-04 15:42:56 +00:00
|
|
|
|
|
2014-04-18 04:17:56 +00:00
|
|
|
|
C++ Format is an open-source formatting library for C++.
|
2014-05-15 02:17:20 +00:00
|
|
|
|
It can be used as a safe alternative to printf or as a fast
|
2013-01-21 20:05:45 +00:00
|
|
|
|
alternative to IOStreams.
|
2012-12-07 22:18:37 +00:00
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
--------
|
|
|
|
|
|
2013-02-28 18:36:37 +00:00
|
|
|
|
* Two APIs: faster concatenation-based write API and slower (but still
|
|
|
|
|
very fast) replacement-based format API with positional arguments for
|
|
|
|
|
localization.
|
2015-02-19 16:26:03 +00:00
|
|
|
|
* Write API similar to the one used by IOStreams but stateless allowing
|
|
|
|
|
faster implementation.
|
2013-01-21 20:05:45 +00:00
|
|
|
|
* Format API with `format string syntax
|
2015-02-05 19:16:39 +00:00
|
|
|
|
<http://cppformat.readthedocs.org/en/latest/syntax.html>`_
|
2012-12-25 03:44:31 +00:00
|
|
|
|
similar to the one used by `str.format
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<http://docs.python.org/2/library/stdtypes.html#str.format>`_ in Python.
|
2015-02-26 17:05:20 +00:00
|
|
|
|
* Safe `printf implementation
|
2015-02-26 16:10:36 +00:00
|
|
|
|
<http://cppformat.readthedocs.org/en/stable/reference.html#printf-formatting-functions>`_
|
|
|
|
|
including the POSIX extension for positional arguments.
|
2012-12-07 22:32:48 +00:00
|
|
|
|
* Support for user-defined types.
|
2013-01-21 20:05:45 +00:00
|
|
|
|
* High speed: performance of the format API is close to that of
|
2014-11-05 15:36:55 +00:00
|
|
|
|
glibc's `printf <http://en.cppreference.com/w/cpp/io/c/fprintf>`_
|
2014-02-13 17:54:10 +00:00
|
|
|
|
and better than performance of IOStreams. See `Speed tests`_ and
|
2014-02-13 17:53:01 +00:00
|
|
|
|
`Fast integer to string conversion in C++
|
|
|
|
|
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
|
2012-12-07 22:18:37 +00:00
|
|
|
|
* Small code size both in terms of source code (format consists of a single
|
2012-12-12 00:30:27 +00:00
|
|
|
|
header file and a single source file) and compiled code.
|
|
|
|
|
See `Compile time and code bloat`_.
|
|
|
|
|
* Reliability: the library has an extensive set of `unit tests
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<https://github.com/cppformat/cppformat/tree/master/test>`_.
|
2012-12-12 00:30:27 +00:00
|
|
|
|
* Safety: the library is fully type safe, errors in format strings are
|
2013-09-08 20:47:38 +00:00
|
|
|
|
reported using exceptions, automatic memory management prevents buffer
|
|
|
|
|
overflow errors.
|
2012-12-12 00:30:27 +00:00
|
|
|
|
* Ease of use: small self-contained code base, no external dependencies,
|
2012-12-12 15:44:41 +00:00
|
|
|
|
permissive BSD `license`_.
|
2014-11-05 15:36:55 +00:00
|
|
|
|
* `Portability <http://cppformat.github.io#portability>`_ with consistent output
|
2014-04-18 15:26:23 +00:00
|
|
|
|
across platforms and support for older compilers.
|
2013-09-03 16:06:49 +00:00
|
|
|
|
* Clean warning-free codebase even on high warning levels
|
|
|
|
|
(-Wall -Wextra -pedantic).
|
2013-09-05 05:03:37 +00:00
|
|
|
|
* Support for wide strings.
|
2015-02-19 16:40:40 +00:00
|
|
|
|
* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro.
|
2012-12-07 22:18:37 +00:00
|
|
|
|
|
2014-11-25 00:20:07 +00:00
|
|
|
|
See the `documentation <http://cppformat.readthedocs.org/en/stable/>`_ for more details.
|
2013-01-21 18:11:59 +00:00
|
|
|
|
|
2012-12-07 22:32:48 +00:00
|
|
|
|
Examples
|
|
|
|
|
--------
|
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
This prints ``Hello, world!`` to stdout:
|
|
|
|
|
|
|
|
|
|
.. code:: c++
|
2012-12-07 22:18:37 +00:00
|
|
|
|
|
2014-07-26 14:25:31 +00:00
|
|
|
|
fmt::print("Hello, {}!", "world"); // uses Python-like format string syntax
|
|
|
|
|
fmt::printf("Hello, %s!", "world"); // uses printf format string syntax
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2013-09-02 17:24:47 +00:00
|
|
|
|
Arguments can be accessed by position and arguments' indices can be repeated:
|
2012-12-13 16:12:09 +00:00
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
.. code:: c++
|
2012-12-09 18:25:38 +00:00
|
|
|
|
|
2014-06-29 18:57:36 +00:00
|
|
|
|
std::string s = fmt::format("{0}{1}{0}", "abra", "cad");
|
2012-12-09 18:25:38 +00:00
|
|
|
|
// s == "abracadabra"
|
|
|
|
|
|
2014-04-18 04:17:56 +00:00
|
|
|
|
C++ Format can be used as a safe portable replacement for ``itoa``:
|
2013-09-06 22:12:46 +00:00
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
.. code:: c++
|
2013-09-06 22:12:46 +00:00
|
|
|
|
|
2014-10-02 13:44:34 +00:00
|
|
|
|
fmt::MemoryWriter w;
|
2013-09-06 22:18:57 +00:00
|
|
|
|
w << 42; // replaces itoa(42, buffer, 10)
|
|
|
|
|
w << fmt::hex(42); // replaces itoa(42, buffer, 16)
|
2013-09-06 22:17:22 +00:00
|
|
|
|
// access the string using w.str() or w.c_str()
|
2013-09-06 22:12:46 +00:00
|
|
|
|
|
2012-12-10 03:22:38 +00:00
|
|
|
|
An object of any user-defined type for which there is an overloaded
|
2013-09-03 20:33:22 +00:00
|
|
|
|
:code:`std::ostream` insertion operator (``operator<<``) can be formatted:
|
2012-12-13 16:12:09 +00:00
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
.. code:: c++
|
2012-12-10 03:19:47 +00:00
|
|
|
|
|
|
|
|
|
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) {
|
2013-09-08 20:47:38 +00:00
|
|
|
|
return os << d.year_ << '-' << d.month_ << '-' << d.day_;
|
2012-12-10 03:19:47 +00:00
|
|
|
|
}
|
|
|
|
|
};
|
|
|
|
|
|
2014-06-29 18:58:21 +00:00
|
|
|
|
std::string s = fmt::format("The date is {}", Date(2012, 12, 9));
|
2012-12-10 03:19:47 +00:00
|
|
|
|
// s == "The date is 2012-12-9"
|
|
|
|
|
|
2014-06-29 18:51:27 +00:00
|
|
|
|
You can use the `FMT_VARIADIC
|
2015-02-05 19:16:39 +00:00
|
|
|
|
<http://cppformat.readthedocs.org/en/latest/reference.html#utilities>`_
|
2014-06-29 18:51:27 +00:00
|
|
|
|
macro to create your own functions similar to `format
|
2015-02-05 19:18:16 +00:00
|
|
|
|
<http://cppformat.readthedocs.org/en/latest/reference.html#format>`_ and
|
2015-02-05 19:16:39 +00:00
|
|
|
|
`print <http://cppformat.readthedocs.org/en/latest/reference.html#print>`_
|
2014-06-29 18:51:27 +00:00
|
|
|
|
which take arbitrary arguments:
|
2012-12-13 16:12:09 +00:00
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
.. code:: c++
|
2012-12-11 21:54:53 +00:00
|
|
|
|
|
2014-06-29 21:22:53 +00:00
|
|
|
|
// Prints formatted error message.
|
2014-09-21 15:13:35 +00:00
|
|
|
|
void report_error(const char *format, fmt::ArgList args) {
|
2014-07-01 23:59:25 +00:00
|
|
|
|
fmt::print("Error: ");
|
2014-06-29 21:22:53 +00:00
|
|
|
|
fmt::print(format, args);
|
2012-12-11 21:54:53 +00:00
|
|
|
|
}
|
2014-06-29 21:22:53 +00:00
|
|
|
|
FMT_VARIADIC(void, report_error, const char *)
|
2014-06-29 18:51:27 +00:00
|
|
|
|
|
2014-06-29 21:22:53 +00:00
|
|
|
|
report_error("file not found: {}", path);
|
2012-12-11 21:54:53 +00:00
|
|
|
|
|
2014-09-21 15:13:35 +00:00
|
|
|
|
Note that you only need to define one function that takes ``fmt::ArgList``
|
|
|
|
|
argument. ``FMT_VARIADIC`` automatically defines necessary wrappers that
|
|
|
|
|
accept variable number of arguments.
|
2012-12-11 21:54:53 +00:00
|
|
|
|
|
2014-01-30 19:16:27 +00:00
|
|
|
|
Projects using this library
|
|
|
|
|
---------------------------
|
|
|
|
|
|
2015-02-06 21:46:19 +00:00
|
|
|
|
* `0 A.D. <http://play0ad.com/>`_: A free, open-source, cross-platform real-time strategy game
|
|
|
|
|
|
2014-10-12 21:18:17 +00:00
|
|
|
|
* `AMPL/MP <https://github.com/ampl/mp>`_:
|
|
|
|
|
An open-source library for mathematical programming
|
2014-01-30 19:16:27 +00:00
|
|
|
|
|
2014-10-12 21:18:17 +00:00
|
|
|
|
* `HarpyWar/pvpgn <https://github.com/HarpyWar/pvpgn>`_:
|
2014-06-29 02:17:13 +00:00
|
|
|
|
Player vs Player Gaming Network with tweaks
|
|
|
|
|
|
2014-09-13 15:44:49 +00:00
|
|
|
|
* `KBEngine <http://www.kbengine.org/>`_: An open-source MMOG server engine
|
|
|
|
|
|
2014-10-12 21:18:17 +00:00
|
|
|
|
* `Lifeline <https://github.com/peter-clark/lifeline>`_: A 2D game
|
|
|
|
|
|
2015-02-07 16:31:17 +00:00
|
|
|
|
* `PenUltima Online (POL) <http://www.polserver.com/>`_:
|
|
|
|
|
An MMO server, compatible with most Ultima Online clients
|
|
|
|
|
|
2014-12-02 14:39:16 +00:00
|
|
|
|
* `readpe <https://bitbucket.org/sys_dev/readpe>`_: Read Portable Executable
|
|
|
|
|
|
2015-02-06 21:46:19 +00:00
|
|
|
|
* `Saddy <https://code.google.com/p/saddy/>`_:
|
|
|
|
|
Small crossplatform 2D graphic engine
|
|
|
|
|
|
2014-12-02 20:54:12 +00:00
|
|
|
|
* `Salesforce Analytics Cloud <http://www.salesforce.com/analytics-cloud/overview/>`_:
|
|
|
|
|
Business intelligence software
|
|
|
|
|
|
2014-12-08 14:15:31 +00:00
|
|
|
|
* `spdlog <https://github.com/gabime/spdlog>`_: Super fast C++ logging library
|
|
|
|
|
|
2015-02-06 22:03:44 +00:00
|
|
|
|
`More... <https://github.com/search?q=cppformat&type=Code>`_
|
|
|
|
|
|
2014-06-29 18:51:27 +00:00
|
|
|
|
If you are aware of other projects using this library, please let me know
|
2014-10-12 21:18:17 +00:00
|
|
|
|
by `email <mailto:victor.zverovich@gmail.com>`_ or by submitting an
|
|
|
|
|
`issue <https://github.com/cppformat/cppformat/issues>`_.
|
2014-01-30 19:16:27 +00:00
|
|
|
|
|
2012-12-07 23:33:27 +00:00
|
|
|
|
Motivation
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
So why yet another formatting library?
|
|
|
|
|
|
|
|
|
|
There are plenty of methods for doing this task, from standard ones like
|
|
|
|
|
the printf family of function and IOStreams to Boost Format library and
|
|
|
|
|
FastFormat. The reason for creating a new library is that every existing
|
|
|
|
|
solution that I found either had serious issues or didn't provide
|
|
|
|
|
all the features I needed.
|
|
|
|
|
|
|
|
|
|
Printf
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
|
|
The good thing about printf is that it is very fast and readily available
|
2014-05-15 02:17:20 +00:00
|
|
|
|
being a part of the C standard library. The main drawback is that it
|
2012-12-09 18:09:15 +00:00
|
|
|
|
doesn't support user-defined types. Printf also has safety issues although
|
2014-11-05 15:36:55 +00:00
|
|
|
|
they are mostly solved with `_attribute__ ((format (printf, ...))
|
|
|
|
|
<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
|
2012-12-09 18:09:15 +00:00
|
|
|
|
There is a POSIX extension that adds positional arguments required for
|
2014-11-05 15:36:55 +00:00
|
|
|
|
`i18n <http://en.wikipedia.org/wiki/Internationalization_and_localization>`_
|
2012-12-09 18:09:15 +00:00
|
|
|
|
to printf but it is not a part of C99 and may not be available on some
|
|
|
|
|
platforms.
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
|
|
|
|
IOStreams
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
2012-12-13 16:12:09 +00:00
|
|
|
|
The main issue with IOStreams is best illustrated with an example:
|
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
.. code:: c++
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
|
|
|
|
std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";
|
|
|
|
|
|
2012-12-13 16:12:09 +00:00
|
|
|
|
which is a lot of typing compared to printf:
|
|
|
|
|
|
2014-11-07 15:04:03 +00:00
|
|
|
|
.. code:: c++
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
|
|
|
|
printf("%.2f\n", 1.23456);
|
|
|
|
|
|
2013-09-02 17:24:47 +00:00
|
|
|
|
Matthew Wilson, the author of FastFormat, referred to this situation with
|
2012-12-09 18:09:15 +00:00
|
|
|
|
IOStreams as "chevron hell". IOStreams doesn't support positional arguments
|
|
|
|
|
by design.
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
|
|
|
|
The good part is that IOStreams supports user-defined types and is safe
|
|
|
|
|
although error reporting is awkward.
|
|
|
|
|
|
|
|
|
|
Boost Format library
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
This is a very powerful library which supports both printf-like format
|
|
|
|
|
strings and positional arguments. The main its drawback is performance.
|
2012-12-09 18:09:15 +00:00
|
|
|
|
According to various benchmarks it is much slower than other methods
|
|
|
|
|
considered here. Boost Format also has excessive build times and severe
|
|
|
|
|
code bloat issues (see `Benchmarks`_).
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
|
|
|
|
FastFormat
|
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
This is an interesting library which is fast, safe and has positional
|
|
|
|
|
arguments. However it has significant limitations, citing its author:
|
|
|
|
|
|
|
|
|
|
Three features that have no hope of being accommodated within the
|
|
|
|
|
current design are:
|
|
|
|
|
|
|
|
|
|
* Leading zeros (or any other non-space padding)
|
|
|
|
|
* Octal/hexadecimal encoding
|
|
|
|
|
* Runtime width/alignment specification
|
|
|
|
|
|
|
|
|
|
It is also quite big and has a heavy dependency, STLSoft, which might be
|
|
|
|
|
too restrictive for using it in some projects.
|
|
|
|
|
|
|
|
|
|
Loki SafeFormat
|
|
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
|
2012-12-17 00:48:08 +00:00
|
|
|
|
SafeFormat is a formatting library which uses printf-like format strings
|
|
|
|
|
and is type safe. It doesn't support user-defined types or positional
|
2012-12-17 00:48:59 +00:00
|
|
|
|
arguments. It makes unconventional use of ``operator()`` for passing
|
2012-12-17 00:48:08 +00:00
|
|
|
|
format arguments.
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
|
|
|
|
Tinyformat
|
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
This library supports printf-like format strings and is very small and
|
|
|
|
|
fast. Unfortunately it doesn't support positional arguments and wrapping
|
2015-02-15 17:32:13 +00:00
|
|
|
|
it in C++98 is somewhat difficult. Also its performance and code compactness
|
|
|
|
|
are limited by IOStreams.
|
2012-12-07 23:33:27 +00:00
|
|
|
|
|
2012-12-25 05:31:05 +00:00
|
|
|
|
Boost Spirit.Karma
|
|
|
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
This is not really a formatting library but I decided to include it here
|
|
|
|
|
for completeness. As IOStreams it suffers from the problem of mixing
|
2014-02-13 17:53:01 +00:00
|
|
|
|
verbatim text with arguments. The library is pretty fast, but slower
|
|
|
|
|
on integer formatting than ``fmt::Writer`` on Karma's own benchmark,
|
|
|
|
|
see `Fast integer to string conversion in C++
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
|
2012-12-25 05:31:05 +00:00
|
|
|
|
|
2015-02-25 17:00:31 +00:00
|
|
|
|
What Users Say
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
Thanks for creating this library. It’s been a hole in C++ for a long time.
|
|
|
|
|
I’ve used both boost::format and loki::SPrintf, and neither felt like the
|
|
|
|
|
right answer. This does.
|
|
|
|
|
|
|
|
|
|
-- Kurt Haas
|
|
|
|
|
|
2012-12-07 21:20:50 +00:00
|
|
|
|
Benchmarks
|
|
|
|
|
----------
|
|
|
|
|
|
2012-12-07 22:32:48 +00:00
|
|
|
|
Speed tests
|
|
|
|
|
~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
The following speed tests results were generated by building
|
2015-02-11 03:32:33 +00:00
|
|
|
|
``tinyformat_test.cpp`` on Ubuntu GNU/Linux 14.04.1 with
|
|
|
|
|
``g++-4.8.2 -O3 -DSPEED_TEST -DHAVE_FORMAT``, and taking the best of three
|
2012-12-07 22:32:48 +00:00
|
|
|
|
runs. In the test, the format string ``"%0.10f:%04d:%+g:%s:%p:%c:%%\n"`` or
|
|
|
|
|
equivalent is filled 2000000 times with output sent to ``/dev/null``; for
|
|
|
|
|
further details see the `source
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<https://github.com/cppformat/format-benchmark/blob/master/tinyformat_test.cpp>`_.
|
2012-12-07 22:32:48 +00:00
|
|
|
|
|
2015-02-17 14:15:44 +00:00
|
|
|
|
================= ============= ===========
|
2015-02-17 14:14:32 +00:00
|
|
|
|
Library Method Run Time, s
|
2015-02-17 14:15:44 +00:00
|
|
|
|
================= ============= ===========
|
2015-02-17 14:12:44 +00:00
|
|
|
|
EGLIBC 2.19 printf 1.30
|
2015-02-17 14:24:40 +00:00
|
|
|
|
libstdc++ 4.8.2 std::ostream 1.85
|
2015-02-17 14:12:44 +00:00
|
|
|
|
C++ Format 1.0 fmt::print 1.42
|
|
|
|
|
tinyformat 2.0.1 tfm::printf 2.25
|
|
|
|
|
Boost Format 1.54 boost::format 9.94
|
2015-02-17 14:15:44 +00:00
|
|
|
|
================= ============= ===========
|
2012-12-07 22:32:48 +00:00
|
|
|
|
|
|
|
|
|
As you can see boost::format is much slower than the alternative methods; this
|
2014-11-05 15:36:55 +00:00
|
|
|
|
is confirmed by `other tests <http://accu.org/index.php/journals/1539>`_.
|
2012-12-07 23:33:27 +00:00
|
|
|
|
Tinyformat is quite good coming close to IOStreams. Unfortunately tinyformat
|
|
|
|
|
cannot be faster than the IOStreams because it uses them internally.
|
2015-02-11 03:37:54 +00:00
|
|
|
|
Performance of cppformat is close to that of printf, being `faster than printf on integer
|
2015-02-11 03:36:29 +00:00
|
|
|
|
formatting <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_,
|
2015-02-11 03:31:22 +00:00
|
|
|
|
but slower on floating-point formatting which dominates this benchmark.
|
2012-12-07 22:32:48 +00:00
|
|
|
|
|
2013-01-09 15:30:01 +00:00
|
|
|
|
Compile time and code bloat
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
2014-05-23 14:00:11 +00:00
|
|
|
|
The script `bloat-test.py
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<https://github.com/cppformat/format-benchmark/blob/master/bloat-test.py>`_
|
|
|
|
|
from `format-benchmark <https://github.com/cppformat/format-benchmark>`_
|
2014-05-22 13:08:50 +00:00
|
|
|
|
tests compile time and code bloat for nontrivial projects.
|
|
|
|
|
It generates 100 translation units and uses ``printf()`` or its alternative
|
|
|
|
|
five times in each to simulate a medium sized project. The resulting
|
|
|
|
|
executable size and compile time (g++-4.8.1, Ubuntu GNU/Linux 13.10,
|
|
|
|
|
best of three) is shown in the following tables.
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2014-05-22 13:08:50 +00:00
|
|
|
|
**Optimized build (-O3)**
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2014-05-23 15:58:28 +00:00
|
|
|
|
============ =============== ==================== ==================
|
|
|
|
|
Method Compile Time, s Executable size, KiB Stripped size, KiB
|
|
|
|
|
============ =============== ==================== ==================
|
|
|
|
|
printf 2.6 41 30
|
|
|
|
|
IOStreams 19.4 92 70
|
|
|
|
|
C++ Format 46.8 46 34
|
|
|
|
|
tinyformat 64.6 418 386
|
|
|
|
|
Boost Format 222.8 990 923
|
|
|
|
|
============ =============== ==================== ==================
|
|
|
|
|
|
|
|
|
|
As you can see, C++ Format has 80% less overhead in terms of resulting
|
|
|
|
|
code size compared to IOStreams and comes pretty close to ``printf``.
|
|
|
|
|
Boost Format has by far the largest overheads.
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2014-05-22 13:08:50 +00:00
|
|
|
|
**Non-optimized build**
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2014-05-23 15:58:28 +00:00
|
|
|
|
============ =============== ==================== ==================
|
|
|
|
|
Method Compile Time, s Executable size, KiB Stripped size, KiB
|
|
|
|
|
============ =============== ==================== ==================
|
|
|
|
|
printf 2.1 41 30
|
|
|
|
|
IOStreams 19.7 86 62
|
|
|
|
|
C++ Format 47.9 108 86
|
|
|
|
|
tinyformat 27.7 234 190
|
|
|
|
|
Boost Format 122.6 884 763
|
|
|
|
|
============ =============== ==================== ==================
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2014-05-23 13:59:03 +00:00
|
|
|
|
``libc``, ``libstdc++`` and ``libformat`` 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.
|
|
|
|
|
|
2012-12-07 21:20:50 +00:00
|
|
|
|
Running the tests
|
|
|
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
2014-12-19 15:50:41 +00:00
|
|
|
|
Please refer to `Building the library`__ for the instructions on how to build
|
|
|
|
|
the library and run the unit tests.
|
2014-12-19 15:49:54 +00:00
|
|
|
|
|
|
|
|
|
__ http://cppformat.readthedocs.org/en/latest/usage.html#building-the-library
|
2014-04-18 04:28:00 +00:00
|
|
|
|
|
2014-05-23 13:59:03 +00:00
|
|
|
|
Benchmarks reside in a separate repository,
|
2014-11-05 15:36:55 +00:00
|
|
|
|
`format-benchmarks <https://github.com/cppformat/format-benchmark>`_,
|
2014-05-23 13:59:03 +00:00
|
|
|
|
so to run the benchmarks you first need to clone this repository and
|
2014-05-23 14:09:41 +00:00
|
|
|
|
generate Makefiles with CMake::
|
2014-05-23 13:59:03 +00:00
|
|
|
|
|
|
|
|
|
$ git clone --recursive https://github.com/cppformat/format-benchmark.git
|
|
|
|
|
$ cd format-benchmark
|
|
|
|
|
$ cmake .
|
|
|
|
|
|
|
|
|
|
Then you can run the speed test::
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2014-05-23 13:59:03 +00:00
|
|
|
|
$ make speed-test
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
|
|
|
|
or the bloat test::
|
|
|
|
|
|
2014-05-22 15:17:30 +00:00
|
|
|
|
$ make bloat-test
|
2012-12-07 21:20:50 +00:00
|
|
|
|
|
2012-12-12 15:44:41 +00:00
|
|
|
|
License
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
Copyright (c) 2012, Victor Zverovich
|
2012-12-13 16:17:56 +00:00
|
|
|
|
|
2012-12-12 15:44:41 +00:00
|
|
|
|
All rights reserved.
|
|
|
|
|
|
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
|
|
|
modification, are permitted provided that the following conditions are met:
|
|
|
|
|
|
|
|
|
|
1. Redistributions of source code must retain the above copyright notice, this
|
|
|
|
|
list of conditions and the following disclaimer.
|
|
|
|
|
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
|
|
|
this list of conditions and the following disclaimer in the documentation
|
|
|
|
|
and/or other materials provided with the distribution.
|
|
|
|
|
|
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
|
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
|
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
|
|
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
|
|
|
|
|
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
|
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
|
|
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
|
|
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
|
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
|
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
|
|
2013-01-14 14:43:31 +00:00
|
|
|
|
Documentation License
|
|
|
|
|
---------------------
|
|
|
|
|
|
2013-01-14 14:47:10 +00:00
|
|
|
|
The `Format String Syntax
|
2015-02-22 19:46:58 +00:00
|
|
|
|
<http://cppformat.readthedocs.org/en/latest/syntax.html>`_
|
2013-01-14 14:43:31 +00:00
|
|
|
|
section in the documentation is based on the one from Python `string module
|
2014-11-05 15:36:55 +00:00
|
|
|
|
documentation <http://docs.python.org/3/library/string.html#module-string>`_
|
2013-01-14 14:43:31 +00:00
|
|
|
|
adapted for the current library. For this reason the documentation is
|
|
|
|
|
distributed under the Python Software Foundation license available in
|
|
|
|
|
`doc/LICENSE.python
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<https://raw.github.com/cppformat/cppformat/master/doc/LICENSE.python>`_.
|
2013-01-14 14:43:31 +00:00
|
|
|
|
|
2012-12-07 21:20:50 +00:00
|
|
|
|
Acknowledgments
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
The benchmark section of this readme file and the performance tests are taken
|
2014-11-05 15:36:55 +00:00
|
|
|
|
from the excellent `tinyformat <https://github.com/c42f/tinyformat>`_ library
|
2012-12-09 18:09:15 +00:00
|
|
|
|
written by Chris Foster. Boost Format library is acknowledged transitively
|
|
|
|
|
since it had some influence on tinyformat.
|
|
|
|
|
Some ideas used in the implementation are borrowed from `Loki
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<http://loki-lib.sourceforge.net/>`_ SafeFormat and `Diagnostic API
|
|
|
|
|
<http://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`_ in
|
|
|
|
|
`Clang <http://clang.llvm.org/>`_.
|
2013-01-14 14:43:31 +00:00
|
|
|
|
Format string syntax and the documentation are based on Python's `str.format
|
2014-11-05 15:36:55 +00:00
|
|
|
|
<http://docs.python.org/2/library/stdtypes.html#str.format>`_.
|
|
|
|
|
Thanks `Doug Turnbull <https://github.com/softwaredoug>`_ for his valuable
|
2013-11-14 16:57:19 +00:00
|
|
|
|
comments and contribution to the design of the type-safe API and
|
2014-11-05 15:36:55 +00:00
|
|
|
|
`Gregory Czajkowski <https://github.com/gcflymoto>`_ for implementing binary
|
|
|
|
|
formatting. Thanks `Ruslan Baratov <https://github.com/ruslo>`_ for comprehensive
|
|
|
|
|
`comparison of integer formatting algorithms <https://github.com/ruslo/int-dec-format-tests>`_
|
|
|
|
|
and useful comments regarding performance, `Boris Kaul <https://github.com/localvoid>`_ for
|
|
|
|
|
`C++ counting digits benchmark <https://github.com/localvoid/cxx-benchmark-count-digits>`_.
|