dynarmic/README.rst
Merry 6633089a44 Squashed 'externals/fmt/' changes from 9e8b86fd2..b6f4ceaed
b6f4ceaed Update version
15f812dae Update changelog
6884aab49 Update changelog
88ec4e706 Bump version
dd3d2490e Update changelog
739055ae7 Fix apidocs
dbbd711f4 Suppress a warning
98cbb6a43 Fix ABI compatiblity issue
214cf13f1 Fix endianness bug in write_digit2_separated (#2699)
17a5c808d Restore FMT_API on error_handler::on_error() (#2696)
fc1783fcc Avoid undefined symbols with mingw-w64 (#2692)
1b193e7b3 Deprecate more
8e59744b8 Switch to new github auth mechanism
7081a6aa3 Update version
64dc8fbad Bump version
fc8e3de7d Fix manage.py script
57bee9fcd Fix formating
dce52e491 Update changelog
9405a4724 Update changelog
495b8bf12 Update changelog
e221166fa Update changelog
035cab8da Update changelog
89c6ed12b Clarify in comments (for now) deprecated map functions
e462da828 Add some noexcept (#2684)
79c66d66b Update changelog
5d37f705f Update changelog
6bb370cec Update changelog
bb6920157 Fix tuple join
4fac7daae Cleanup bit_cast
3617c2795 Update changelog
9c0c1bcdb Simplify tuple formatting
187e8db1b Update changelog
c7f88180f add tests for format string compile-time checks
8a2c3fb88 add reverse tests to compile-error-test
1164eda5a disable compile-error-test on Windows
4482f6f1f rewrite compile-error-test to use non-header-only library
796662a61 Escape range items convertible to std::string_view
33ee4cc51 Improve noexception test
3bbf2c673 Fix throw with exceptions disabled
074c9c52e Update changelog
3110ec5a2 Update changelog
3014b3d77 Clarify that C strings must be null-terminated
eab2ea9fc Replace an assert with an exception
21ed92a6e Update changelog
04111dd1e Fix issue #2670 (#2671)
817788fbf remove incorrect C++20 check from test/CMakeLists.txt (#2663)
4511030af Minor code style tweaks for consistency
7812813a3 Don't explicitly delete copy ctor of dynamic_format_arg_store (#2664)
664cd6067 Remove std-format-test
784e2a7b4 Fix an overflow when formatting very large durations
fc2a376d8 Remove two expressions which had no effect (reported by LGTM)
c5aafd8f9 expose headers as SYSTEM depending on special configuration option
eaddd1e3c Fix handling of byte
2d4457758 Try fixing byte regression
e46392ea2 deprecate _format UDL in code using FMT_DEPRECATED
c882790a2 Add a set formatter
121002d70 Add a map formatter
be51ee1ce Disable broken copy ctor of dynamic_format_arg_store
659de779e Fix a UB in parse_format_specs when begin is null
51b14b6c0 remove commented out lines
223a0fa55 move gtest-specific check into gtest/CMakeLists.txt
ef72b471f enable named arguments check in compile-time checks (#2649)
82246b876 fix throw with exceptions disabled (#2647)
35f60377a Update ChangeLog.rst
3a951a66c Avoid qualifying by inline namespace. Fixes #2642. (#2643)
e0136fc8b Qualify calls to make_wformat_args. Fixes #2639. (#2641)
ac1b5f3da Refactor problematic trailing returns in arg_mapper
fd62fba98 Don't convert scoped enums to integers
c652f8243 Make header guard consistent with header name
a9c7b9b8f Clarify that _format is deprecated
e4f0564aa Disable is_streamable for string[_view]
91533d3c3 Minor tweaks to chrono subsecond formatting
0bbc9708f Implement c++20 std::chrono::duration subsecond formatting (#2623)
9d5b9defd Enable tzset only on Windows desktop app (#2633)
215f21a03 Detect overflow on large precision
c240d98ff Optimize tm formatting (Non C-locales and %Z) (#2617)
6ab73113f Mark grow as FMT_CONSTEXPR20 (#2630)
713c7c7c6 Cleanup os.cc
9b1807a8a fix int -> uint warning (#2611)
ec3b097cb [doc] FMT_STRING supports C++14 and no-op in C++11 (#2620)
c472a2781 Fix handling of very large precision in fixed format
201971e29 Make MSVC use [[nodiscard]] (#2615)
acad8cfab Reformat all source code; no functional changes
491ba2dda Annotate fmt::format and fmt::formatted_size as [[nodiscard]]
5abe9e826 Add platform-specific 'z' formatter
be3a3a5ae Use predefined formats for C-locale
a3ab36c80 Formatting of function pointers, member function pointers, member object pointers... (#2610)
19cac63fe Broken link in README.rst
43419a4ad Workaround a bug in gcc
c089f7d49 Simplify std::tm formatter
aa5517f6b Reuse tm_writer in chrono_formatter
50140be7a Reuse tm_writer in weekday formatter
8b8945499 Improve consistency
5380ff4d8 Detect types convertible to unformattable pointers
094b66e81 changed locale retrieval way to a fancy one
b69ae4854 Reorder classes (#2591)
0b843af56 sped up chrono.h formatting for cases without providing locale (#2576)
12b1d8b14 Fix precision 0 with std::chrono::duration and added additional tests. (#2588)
e67f92c55 Cleanup warnings with nvhpc/21.9. (#2582)
812733cc9 const qualify format function for systen_clock
028f22775 Handle implicit conversions in write
5b0aa638c Minor grammar fix
6eaceb5f7 Fix incompatible between docutils 1.18.0 and sphinx 3.3.0 (#2575)
0697c5edb FMT_USE_FCNTL can be predefined (#2573)
1031eedf2 Replacing strftime with std::time_put (#2550)
90034e4c4 Add FMT_ASSERT and validation of values of struct tm members (#2564)
df40e9467 Upgrade `module-test` to msvc 16.11.5 and 17.0-pre5 (#2558)
e6d5059cb Simplify js tag in basic-bootstrap theme (#2562)
3b6e409cd Enable `consteval` for msvc 17.0-pre5 (#2559)
249f03bbb do not detect LLVM based IBMXL compiler (on ppc) as clang (#2555)
7463c8320 Fix overflow for very bigger years (>2*10^9) (#2551)
1266c2b60 Fix handling of exotic character types
684e2fdc9 Minor cleanup
a1d586302 Minor cleanup
7a604cdd9 Cleanup
aeb54b0dd Fix bug on '%Y' and '%C' formats with negative years Requested changes
f88c020fc Generalization of strftime/wcsftime function calls in tests
2eeddba75 Renaming, splitting of functions
275454608 Fix errors in ISO week-base-year formatter
218cecb6d Fix error in test
e9f4453b0 Fix Microsoft Visual Studio 14.0 build
27c3674ce Improve performance
5dc3dd3d4 New tests
f8542cd98 Unified formatters for std::chrono::time_point<std::chrono::system_clock, Duration> and std::tm
4707373d3 Fix year formatter
79c00ad8f Improve ISO week-base-year formatter
fbaaa5906 Improve week of the year formatter
cde44ddb7 Improve year formatter
b04601b91 Switch from std::strftime/std::wcsftime to internal implementation for locale independent formats
d3d30a46f New tests
7911d8d3f Add format spec checker
fbbfc3b03 Reorder formatters
509eac957 Workarounds for implementation-defined std::strftime behavior
85b38190d New tests for all C++11 std::strftime format specifiers
7aca36bca Extending fmt::join to support C++20-only ranges. (#2549)
f5371a75f locale.h -> format.h
febdef43f fix: add workaround for intel parameter pack bug
f56756986 fix: check to make sure both 'if constexpr' and return type deduction are available
dcd282bb2 Namespace qualify calls to get
9c14474d3 Include `<bit>` when using `std::bit_cast`
1e96e0176 Fix compiler flag check (#2540)
7e4bc9451 Speeding up write_significand() (#2499)
26c1ca4c3 Replaced default spec with equivalent one, which is potentially more optimizable (#2537)
1e865b353 Fix docs
4a85db1ce Change default open mode to -rw-r--r-- (#2530)
0a985fd4c Move size_ initialization to initializer list (#2529)
012cc709d Workaround gcc _Pragma bug 59884
d6590e3bd Fix compiler check
134aec40f Fix search in docs
48a476ae0 Update example (#2522)
023c2018f Don't use strlen in constexpr
800d4c8ac Refactor Windows workarounds
32865aeaa changed detection of Intel Compiler Classic to distinguish MS-Windows (#2510)
7b339795a Describe a better approach of how to use {fmt} as a depency in a Bazel project (#2516)
ae9bbe116 Suppress warning C4127 in chrono.h (conditional expression is constant) (#2518)
927dbd134 Misplaced comma in README.rst (#2515)
2a9a77dd8 Remove misplaced comment
1aee4bc90 Refactor FP formatting
e1bd6cc91 Refactor FP formatting
027fcaf05 Replace use_grisu with fallback since Grisu is only one of multiple implemented algorithms
716d69f27 Refactor FP formatting
ff7e73af6 Always run grisu_gen_digits before fallback_format
2976e31ac Refactor format_float
807ee5ec3 Disable consteval in Apple clang
d9a731d48 Add basic support for Bazel (#2505)
9c57357e0 Add `static` to a table (#2509)
2742611ca Fix formatting
5092b198b Document group_digits
b4d9d82e1 make FP formatting available to be used at compile-time (#2426)
d9fd695ac Fix wchar_t tm formatting
92614ecbf Optimize %T in tm formatting
aaeca12d8 Move FMT_MAYBE_UNUSED to format.h where it is used
3d0c7ae38 Move data to format.cc
04e3a79f7 Use memcpy in more cases in copy2
e47e99bb0 Simplify format_decimal (#2498)
9b6b0e403 Remove data
4d1c6034e Deprecate basic_data
a3348eccd Deprecate most of basic_data
3a0448148 Remove data::hex_digits
ad77331c0 Move log10_2_significand to format-inl.h
d9ebc4e82 Add a function to get sign char
c00eb4f4c Add missing inline
25af02f21 positive -> nonnegative (#2493)
67cb2dad3 Optimize %F in tm formatting
1aa98f8b9 Eliminate double copying in vformat_to_n (#2489)
a58c13382 Improve code_point_length codegen on older gcc
aeee70a81 Remove unnecessary cast
c771ba361 Fix build for the clang-10 / libstdc++-9 couple (#2491)
ab6e2272c Clarify shifts encoding
e4728409e Use throw_format_error in more places to reduce bloat
e3ebf366a Inline padding shifts
894faf3fe Refactor presentation types
4eb97fa4e Reduce code bloat
6b55c8325 is_const_formattable -> has_const_formatter
2fe94ad7e Make specifiers support in tuple_join an opt-in
3940de595 thousands -> group_digits
c4d0f96a6 Implement format specs in fmt::thousands
3b9c44268 Implement thousands separators without locales
08f98c7fa Simplify get_arg_index_by_name
a151f955a Remove FMT_OVERRIDE
42a225cbd Remove redundand final
bf20d1990 Simplify the core API
fc0884037 Move FMT_GCC_VISIBILITY_HIDDEN to format.h
1aeed2dbc Require inline namespaces
799bea473 Remove FMT_HAS_GXX_CXX11
60cd5ea3f Add support for more formattable types in ranges
4fd9a00f3 Simplify ostream interface
568156389 Cleanup ostream interface
20931baf1 Disable fallback_formatter for arrays
d58d19ba3 Fix an odr violation in ranges.h (#2483)
ee0659f8b Fix formatting of abstract classes via ostream
8029bf955 Fix copy_str performance (#2477)
2520f410c Workaround for #2478 (#2482)
ee63f5f04 Workaround to MSVC bug (#2474) (#2476)
1aaf72fb6 Add an example to fmt::runtime
c1313c205 Clarify that format_to[_n] do not append a terminating null
cb0f177c3 Improve docs
71677e520 Improve docs
4db572352 add fuzzers for chrono timepoint and localtime,gmtime (#2469)
dc7f3ef2b Fix header name
419ba86a9 Improve docs
6a5b4d5fa Document format_string
2599163b8 Document format_string
8ef22f774 Update docs
c0c4d1ada Update docs
729a44e67 Depreate strtod and remove problematic tests
74c111896 Apply force inline
596508a92 Cleanup
043e3b342 Remove static_assert from arg_mapper
8b0cb944d Fix error reporting when mixing character types
117fc6707 CI: replace g++ C++20 build to test FP formatting at compile-time
c79a3841e make detail::fp and detail::bigit constexpr
5888de9f3 make detail::make_checked() constexpr
04b4b69b1 make detail::bit_cast() constexpr with C++20
fd34a3d24 make detail::basic_memory_buffer constexpr with C++20
6d597e39c Fix overload ambiguity in arg_mapper
b9ce56d93 Improve comments
f889e52a1 Improve error reporting
34caecd6b Use consistent initialization style
a44c8f651 reimplement `formatter<tuple_join_view>` (#2457)
4b8bda25c Fix 2462
6b5e6119e set clang in one place
7af1dc1d2 fix UB in fuzzer common (memcpy on nullptr)
e77686f7a clang format
2207ea0b3 More escaping
a212ff757 Escape invalid code points
a76031e11 check -> is_printable
a7f280765 Improve naming
07d033ecb Fix is_printable
cdb4299ac Add Unicode support to is_printable
7df2c82a8 Rewrite printable.py codegen to emit C++
6cf90d7ce Add script license and fix python version
2f1ad8ed3 Add printable codegen from Rust
371d8e2ee Escape Unicode
6397095ca More escaping
f69a57253 Don't overescape wide strings
11b07a56b We should escape
b559cfd4c Implement basic escaping
11d49491c Handle global locale
6ea6cf946 Add decimal separator support to float
9730a2af0 Update ChangeLog.rst
c2ed5f686 Update ChangeLog.rst
7b66e72e2 Use builtin intrinsics on intel (#2450)
d57b2a652 Suppress a warning
bdfbd794e Cleanup begin/end usage
111de881f Don't copy non-const-iterable ranges
d6e882ed8 Undo the move because the doc is not a GH template
f488eed10 Resolve default constructor error in Xcode 7.2.1 and 8.2.1
652c3653b Move CONTRIBUTING.md to .github
fb19faa31 Improves README with svg badge (#2446)
07211701f Disable the -Wstringop-overflow warning from GCC 7 (#2442)
bba0a9d96 Make flush public
f1794a885 Switch to threadsafe death test style
0544a2279 Exclude fallback functions when FMT_BUILTIN_CLZ(LL) is not defined (#2434)
5c222f056 Add support for nonconst formattable types
3def950b8 Set FMT_CAN_MODULE=OFF for MSVC 19.29.30035+
63fe2d5bd Add copy constructor for dynamic_format_arg_store, and test
561834650 Improve digit count
f20f50368 Replace `throw` with `FMT_THROW` (#2427)
00235d8a9 fix module test odr violations (#2414)
2038bf618 Update format_to usage
e41ac1f87 Don't use deprecated API in docs
8465869d7 Move ignore_unused to detail
3d53d1539 Warning removals in test code (#2399)
20e4ef8b4 Pass significand_size by value
c4a3c2342 Refactor locale handling
7a0d30175 Update README.rst
f2b03facd Include test sources to pick up functions and classes from the module rather than from the non-modular library which is baked into the `test-main` library. (#2356)
02ad5e11d Add faint, blink, reverse and conceal to the emphases (#2394)
d141cdbeb Update version
cfc05e05f Bump version
8ea312633 Update changelog
e461f3dbb Minor consitency and comment tweaks
54014e42e silence warning C4100 on MSVC 2019 when exceptions are disabled (#2397)
3e7a29cc9 Workaround clang/gcc incompatibility
00a57a9f8 Update changelog
1d7384530 Add missing presentation type checks for std::string (#2402)
889bbf27a Fix missing std::get overload in MSVC (#2407)
5f8473914 Remove outdated apidoc
785908ee3 Fix warnings
fbb70eec5 suppress unused variable warnings (#2381)
002bb759f Remove unneeded `num_result_bigits` decrement
a3f762c5a [doc] Minor: fix ``code``.
c3c27e5ab Fix MSVC warning C4819
c6b1f181a Fix docs
94564b058 Fix docs
0fc73a2a8 Merge branch 'master' of github.com:fmtlib/fmt
3156fcf5f Switch to older breathe version
f85fb9fdf Adjust definition for FMT_HAS_INCLUDE
0bc3d664e Fix docs
e5c46e13e Fix docs: breathe 18 and earlier corrupts trailing return type
49a3b58c8 Specify size for static data arrays
d0c8d45a2 apt update before install
c9a10631c format: do not use udl_{arg,formatter} return types when UDL is not in use
3bd806f12 Eliminate intel compiler warning
fd16bcb20 Fix bug in cmake join function
5221242f6 Instruct msvc to report the _true_ value in `__cplusplus` and force _full_ C++ conformance
31a5f0d39 Bump version in inline namespace
102a4d492 Bump version in inline namespace
f68508b6c Update ChangeLog.rst

git-subtree-dir: externals/fmt
git-subtree-split: b6f4ceaed0a0a24ccf575fab6c56dd50ccf6f1a9
2022-02-15 11:15:34 +00:00

528 lines
19 KiB
ReStructuredText

{fmt}
=====
.. image:: https://github.com/fmtlib/fmt/workflows/linux/badge.svg
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Alinux
.. image:: https://github.com/fmtlib/fmt/workflows/macos/badge.svg
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Amacos
.. image:: https://github.com/fmtlib/fmt/workflows/windows/badge.svg
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Awindows
.. image:: https://ci.appveyor.com/api/projects/status/ehjkiefde6gucy1v?svg=true
:target: https://ci.appveyor.com/project/vitaut/fmt
.. image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/fmt.svg
:alt: fmt is continuously fuzzed at oss-fuzz
:target: https://bugs.chromium.org/p/oss-fuzz/issues/list?\
colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20\
Summary&q=proj%3Dfmt&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 providing a fast and safe
alternative to C stdio and C++ iostreams.
If you like this project, please consider donating to the BYSOL
Foundation that helps victims of political repressions in Belarus:
https://bysol.org/en/bs/general/.
`Documentation <https://fmt.dev>`__
Q&A: ask questions on `StackOverflow with the tag fmt
<https://stackoverflow.com/questions/tagged/fmt>`_.
Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763>`_.
Features
--------
* Simple `format API <https://fmt.dev/latest/api.html>`_ with positional arguments
for localization
* Implementation of `C++20 std::format
<https://en.cppreference.com/w/cpp/utility/format>`__
* `Format string syntax <https://fmt.dev/latest/syntax.html>`_ similar to Python's
`format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
* Fast IEEE 754 floating-point formatter with correct rounding, shortness and
round-trip guarantees
* Safe `printf implementation
<https://fmt.dev/latest/api.html#printf-formatting>`_ including the POSIX
extension for positional arguments
* Extensibility: `support for user-defined types
<https://fmt.dev/latest/api.html#formatting-user-defined-types>`_
* High performance: faster than common standard library implementations of
``(s)printf``, iostreams, ``to_string`` and ``to_chars``, see `Speed tests`_
and `Converting a hundred million integers to strings per second
<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
* Small code size both in terms of source code with the minimum configuration
consisting of just three 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 `tests
<https://github.com/fmtlib/fmt/tree/master/test>`_ and is `continuously fuzzed
<https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20
Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dfmt&can=1>`_
* 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 MIT `license
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
* `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 such as
``-Wall -Wextra -pedantic``
* Locale-independence by default
* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro
See the `documentation <https://fmt.dev>`_ for more details.
Examples
--------
**Print to stdout** (`run <https://godbolt.org/z/Tevcjh>`_)
.. code:: c++
#include <fmt/core.h>
int main() {
fmt::print("Hello, world!\n");
}
**Format a string** (`run <https://godbolt.org/z/oK8h33>`_)
.. code:: c++
std::string s = fmt::format("The answer is {}.", 42);
// s == "The answer is 42."
**Format a string using positional arguments** (`run <https://godbolt.org/z/Yn7Txe>`_)
.. code:: c++
std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy");
// s == "I'd rather be happy than right."
**Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc>`_)
.. code:: c++
#include <fmt/chrono.h>
int main() {
using namespace std::literals::chrono_literals;
fmt::print("Default format: {} {}\n", 42s, 100ms);
fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
}
Output::
Default format: 42s 100ms
strftime-like format: 03:15:30
**Print a container** (`run <https://godbolt.org/z/MjsY7c>`_)
.. code:: c++
#include <vector>
#include <fmt/ranges.h>
int main() {
std::vector<int> v = {1, 2, 3};
fmt::print("{}\n", v);
}
Output::
[1, 2, 3]
**Check a format string at compile time**
.. code:: c++
std::string s = fmt::format("{:d}", "I am not a number");
This gives a compile-time error in C++20 because ``d`` is an invalid format
specifier for a string.
**Write a file from a single thread**
.. code:: c++
#include <fmt/os.h>
int main() {
auto out = fmt::output_file("guide.txt");
out.print("Don't {}", "Panic");
}
This can be `5 to 9 times faster than fprintf
<http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html>`_.
**Print with colors and text styles**
.. code:: c++
#include <fmt/color.h>
int main() {
fmt::print(fg(fmt::color::crimson) | fmt::emphasis::bold,
"Hello, {}!\n", "world");
fmt::print(fg(fmt::color::floral_white) | bg(fmt::color::slate_gray) |
fmt::emphasis::underline, "Hello, {}!\n", "мир");
fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic,
"Hello, {}!\n", "世界");
}
Output on a modern terminal:
.. image:: https://user-images.githubusercontent.com/
576385/88485597-d312f600-cf2b-11ea-9cbe-61f535a86e28.png
Benchmarks
----------
Speed tests
~~~~~~~~~~~
================= ============= ===========
Library Method Run Time, s
================= ============= ===========
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, ~35% faster than ``printf``.
The above results were generated by building ``tinyformat_test.cpp`` on macOS
10.14.6 with ``clang++ -O3 -DNDEBUG -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/src/tinyformat-test.cc>`_.
{fmt} is up to 20-30x faster than ``std::ostringstream`` and ``sprintf`` on
floating-point formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
and faster than `double-conversion <https://github.com/google/double-conversion>`_ and
`ryu <https://github.com/ulfjack/ryu>`_:
.. image:: https://user-images.githubusercontent.com/576385/
95684665-11719600-0ba8-11eb-8e5b-972ff4e49428.png
:target: https://fmt.dev/unknown_mac64_clang12.0.html
Compile time and code bloat
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The script `bloat-test.py
<https://github.com/fmtlib/format-benchmark/blob/master/bloat-test.py>`_
from `format-benchmark <https://github.com/fmtlib/format-benchmark>`_
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 (Apple LLVM version 8.1.0 (clang-802.0.42),
macOS Sierra, best of three) is shown in the following tables.
**Optimized build (-O3)**
============= =============== ==================== ==================
Method Compile Time, s Executable size, KiB Stripped size, KiB
============= =============== ==================== ==================
printf 2.6 29 26
printf+string 16.4 29 26
iostreams 31.1 59 55
{fmt} 19.0 37 34
Boost Format 91.9 226 203
Folly Format 115.7 101 88
============= =============== ==================== ==================
As you can see, {fmt} has 60% less overhead in terms of resulting binary code
size compared to iostreams and comes pretty close to ``printf``. Boost Format
and Folly Format have the largest overheads.
``printf+string`` is the same as ``printf`` but with extra ``<string>``
include to measure the overhead of the latter.
**Non-optimized build**
============= =============== ==================== ==================
Method Compile Time, s Executable size, KiB Stripped size, KiB
============= =============== ==================== ==================
printf 2.2 33 30
printf+string 16.0 33 30
iostreams 28.3 56 52
{fmt} 18.2 59 50
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 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.
__ https://fmt.dev/latest/usage.html#building-the-library
Benchmarks reside in a separate repository,
`format-benchmarks <https://github.com/fmtlib/format-benchmark>`_,
so to run the benchmarks you first need to clone this repository and
generate Makefiles with CMake::
$ git clone --recursive https://github.com/fmtlib/format-benchmark.git
$ cd format-benchmark
$ cmake .
Then you can run the speed test::
$ make speed-test
or the bloat test::
$ make bloat-test
Migrating code
--------------
`clang-tidy-fmt <https://github.com/mikecrowe/clang-tidy-fmt>`_ provides clang
tidy checks for converting occurrences of ``printf`` and ``fprintf`` to
``fmt::print``.
Projects using this library
---------------------------
* `0 A.D. <https://play0ad.com/>`_: a free, open-source, cross-platform
real-time strategy game
* `2GIS <https://2gis.ru/>`_: free business listings with a city map
* `AMPL/MP <https://github.com/ampl/mp>`_:
an open-source library for mathematical programming
* `Aseprite <https://github.com/aseprite/aseprite>`_:
animated sprite editor & pixel art tool
* `AvioBook <https://www.aviobook.aero/en>`_: a comprehensive aircraft
operations suite
* `Blizzard Battle.net <https://battle.net/>`_: an online gaming platform
* `Celestia <https://celestia.space/>`_: real-time 3D visualization of space
* `Ceph <https://ceph.com/>`_: a scalable distributed storage system
* `ccache <https://ccache.dev/>`_: a compiler cache
* `ClickHouse <https://github.com/ClickHouse/ClickHouse>`_: analytical database
management system
* `CUAUV <https://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
* `fmtlog <https://github.com/MengRao/fmtlog>`_: a performant fmtlib-style
logging library with latency in nanoseconds
* `Folly <https://github.com/facebook/folly>`_: Facebook open-source library
* `Grand Mountain Adventure
<https://store.steampowered.com/app/1247360/Grand_Mountain_Adventure/>`_:
A beautiful open-world ski & snowboarding game
* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
Player vs Player Gaming Network with tweaks
* `KBEngine <https://github.com/kbengine/kbengine>`_: an open-source MMOG server
engine
* `Keypirinha <https://keypirinha.com/>`_: a semantic launcher for Windows
* `Kodi <https://kodi.tv/>`_ (formerly xbmc): home theater software
* `Knuth <https://kth.cash/>`_: high-performance Bitcoin full-node
* `Microsoft Verona <https://github.com/microsoft/verona>`_:
research programming language for concurrent ownership
* `MongoDB <https://mongodb.com/>`_: distributed document database
* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: a small tool to
generate randomized datasets
* `OpenSpace <https://openspaceproject.com/>`_: an open-source
astrovisualization framework
* `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
* `Quill <https://github.com/odygrd/quill>`_: asynchronous low-latency logging library
* `QKW <https://github.com/ravijanjam/qkw>`_: generalizing aliasing to simplify
navigation, and executing complex multi-line terminal command sequences
* `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
* `Salesforce Analytics Cloud
<https://www.salesforce.com/analytics-cloud/overview/>`_:
business intelligence software
* `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++
framework for high-performance server applications on modern hardware
* `spdlog <https://github.com/gabime/spdlog>`_: super fast C++ logging library
* `Stellar <https://www.stellar.org/>`_: financial platform
* `Touch Surgery <https://www.touchsurgery.com/>`_: surgery simulator
* `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: open-source
MMORPG framework
* `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
`issue <https://github.com/fmtlib/fmt/issues>`_.
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 and FastFormat
libraries. 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 pretty fast and readily available
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, ...))
<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
platforms.
iostreams
~~~~~~~~~
The main issue with iostreams is best illustrated with an example:
.. code:: c++
std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";
which is a lot of typing compared to printf:
.. code:: c++
printf("%.2f\n", 1.23456);
Matthew Wilson, the author of FastFormat, called this "chevron hell". iostreams
don't support positional arguments by design.
The good part is that iostreams support user-defined types and are safe although
error handling is awkward.
Boost Format
~~~~~~~~~~~~
This is a very powerful library which supports both ``printf``-like format
strings and positional arguments. Its main drawback is performance. 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`_).
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.
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 verbatim text
with arguments. The library is pretty fast, but slower on integer formatting
than ``fmt::format_to`` with format string compilation on Karma's own benchmark,
see `Converting a hundred million integers to strings per second
<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_.
License
-------
{fmt} is distributed under the MIT `license
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.
Documentation License
---------------------
The `Format String Syntax <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>`_.
For this reason the documentation is distributed under the Python Software
Foundation license available in `doc/python-license.txt
<https://raw.github.com/fmtlib/fmt/master/doc/python-license.txt>`_.
It only applies if you distribute the documentation of {fmt}.
Maintainers
-----------
The {fmt} library is maintained by Victor Zverovich (`vitaut
<https://github.com/vitaut>`_) and Jonathan Müller (`foonathan
<https://github.com/foonathan>`_) with contributions from many other people.
See `Contributors <https://github.com/fmtlib/fmt/graphs/contributors>`_ and
`Releases <https://github.com/fmtlib/fmt/releases>`_ for some of the names.
Let us know if your contribution is not listed or mentioned incorrectly and
we'll make it right.