2
0

README.rst 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531
  1. .. image:: https://user-images.githubusercontent.com/
  2. 576385/156254208-f5b743a9-88cf-439d-b0c0-923d53e8d551.png
  3. :width: 25%
  4. :alt: {fmt}
  5. .. image:: https://github.com/fmtlib/fmt/workflows/linux/badge.svg
  6. :target: https://github.com/fmtlib/fmt/actions?query=workflow%3Alinux
  7. .. image:: https://github.com/fmtlib/fmt/workflows/macos/badge.svg
  8. :target: https://github.com/fmtlib/fmt/actions?query=workflow%3Amacos
  9. .. image:: https://github.com/fmtlib/fmt/workflows/windows/badge.svg
  10. :target: https://github.com/fmtlib/fmt/actions?query=workflow%3Awindows
  11. .. image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/fmt.svg
  12. :alt: fmt is continuously fuzzed at oss-fuzz
  13. :target: https://bugs.chromium.org/p/oss-fuzz/issues/list?\
  14. colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20\
  15. Summary&q=proj%3Dfmt&can=1
  16. .. image:: https://img.shields.io/badge/stackoverflow-fmt-blue.svg
  17. :alt: Ask questions at StackOverflow with the tag fmt
  18. :target: https://stackoverflow.com/questions/tagged/fmt
  19. **{fmt}** is an open-source formatting library providing a fast and safe
  20. alternative to C stdio and C++ iostreams.
  21. If you like this project, please consider donating to one of the funds that
  22. help victims of the war in Ukraine: https://www.stopputin.net/.
  23. `Documentation <https://fmt.dev>`__
  24. `Cheat Sheets <https://hackingcpp.com/cpp/libs/fmt.html>`__
  25. Q&A: ask questions on `StackOverflow with the tag fmt
  26. <https://stackoverflow.com/questions/tagged/fmt>`_.
  27. Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763>`_.
  28. Features
  29. --------
  30. * Simple `format API <https://fmt.dev/latest/api.html>`_ with positional arguments
  31. for localization
  32. * Implementation of `C++20 std::format
  33. <https://en.cppreference.com/w/cpp/utility/format>`__
  34. * `Format string syntax <https://fmt.dev/latest/syntax.html>`_ similar to Python's
  35. `format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
  36. * Fast IEEE 754 floating-point formatter with correct rounding, shortness and
  37. round-trip guarantees
  38. * Safe `printf implementation
  39. <https://fmt.dev/latest/api.html#printf-formatting>`_ including the POSIX
  40. extension for positional arguments
  41. * Extensibility: `support for user-defined types
  42. <https://fmt.dev/latest/api.html#formatting-user-defined-types>`_
  43. * High performance: faster than common standard library implementations of
  44. ``(s)printf``, iostreams, ``to_string`` and ``to_chars``, see `Speed tests`_
  45. and `Converting a hundred million integers to strings per second
  46. <http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
  47. * Small code size both in terms of source code with the minimum configuration
  48. consisting of just three files, ``core.h``, ``format.h`` and ``format-inl.h``,
  49. and compiled code; see `Compile time and code bloat`_
  50. * Reliability: the library has an extensive set of `tests
  51. <https://github.com/fmtlib/fmt/tree/master/test>`_ and is `continuously fuzzed
  52. <https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20
  53. Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dfmt&can=1>`_
  54. * Safety: the library is fully type safe, errors in format strings can be
  55. reported at compile time, automatic memory management prevents buffer overflow
  56. errors
  57. * Ease of use: small self-contained code base, no external dependencies,
  58. permissive MIT `license
  59. <https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
  60. * `Portability <https://fmt.dev/latest/index.html#portability>`_ with
  61. consistent output across platforms and support for older compilers
  62. * Clean warning-free codebase even on high warning levels such as
  63. ``-Wall -Wextra -pedantic``
  64. * Locale-independence by default
  65. * Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro
  66. See the `documentation <https://fmt.dev>`_ for more details.
  67. Examples
  68. --------
  69. **Print to stdout** (`run <https://godbolt.org/z/Tevcjh>`_)
  70. .. code:: c++
  71. #include <fmt/core.h>
  72. int main() {
  73. fmt::print("Hello, world!\n");
  74. }
  75. **Format a string** (`run <https://godbolt.org/z/oK8h33>`_)
  76. .. code:: c++
  77. std::string s = fmt::format("The answer is {}.", 42);
  78. // s == "The answer is 42."
  79. **Format a string using positional arguments** (`run <https://godbolt.org/z/Yn7Txe>`_)
  80. .. code:: c++
  81. std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy");
  82. // s == "I'd rather be happy than right."
  83. **Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc>`_)
  84. .. code:: c++
  85. #include <fmt/chrono.h>
  86. int main() {
  87. using namespace std::literals::chrono_literals;
  88. fmt::print("Default format: {} {}\n", 42s, 100ms);
  89. fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
  90. }
  91. Output::
  92. Default format: 42s 100ms
  93. strftime-like format: 03:15:30
  94. **Print a container** (`run <https://godbolt.org/z/MxM1YqjE7>`_)
  95. .. code:: c++
  96. #include <vector>
  97. #include <fmt/ranges.h>
  98. int main() {
  99. std::vector<int> v = {1, 2, 3};
  100. fmt::print("{}\n", v);
  101. }
  102. Output::
  103. [1, 2, 3]
  104. **Check a format string at compile time**
  105. .. code:: c++
  106. std::string s = fmt::format("{:d}", "I am not a number");
  107. This gives a compile-time error in C++20 because ``d`` is an invalid format
  108. specifier for a string.
  109. **Write a file from a single thread**
  110. .. code:: c++
  111. #include <fmt/os.h>
  112. int main() {
  113. auto out = fmt::output_file("guide.txt");
  114. out.print("Don't {}", "Panic");
  115. }
  116. This can be `5 to 9 times faster than fprintf
  117. <http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html>`_.
  118. **Print with colors and text styles**
  119. .. code:: c++
  120. #include <fmt/color.h>
  121. int main() {
  122. fmt::print(fg(fmt::color::crimson) | fmt::emphasis::bold,
  123. "Hello, {}!\n", "world");
  124. fmt::print(fg(fmt::color::floral_white) | bg(fmt::color::slate_gray) |
  125. fmt::emphasis::underline, "Hello, {}!\n", "мир");
  126. fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic,
  127. "Hello, {}!\n", "世界");
  128. }
  129. Output on a modern terminal:
  130. .. image:: https://user-images.githubusercontent.com/
  131. 576385/88485597-d312f600-cf2b-11ea-9cbe-61f535a86e28.png
  132. Benchmarks
  133. ----------
  134. Speed tests
  135. ~~~~~~~~~~~
  136. ================= ============= ===========
  137. Library Method Run Time, s
  138. ================= ============= ===========
  139. libc printf 1.04
  140. libc++ std::ostream 3.05
  141. {fmt} 6.1.1 fmt::print 0.75
  142. Boost Format 1.67 boost::format 7.24
  143. Folly Format folly::format 2.23
  144. ================= ============= ===========
  145. {fmt} is the fastest of the benchmarked methods, ~35% faster than ``printf``.
  146. The above results were generated by building ``tinyformat_test.cpp`` on macOS
  147. 10.14.6 with ``clang++ -O3 -DNDEBUG -DSPEED_TEST -DHAVE_FORMAT``, and taking the
  148. best of three runs. In the test, the format string ``"%0.10f:%04d:%+g:%s:%p:%c:%%\n"``
  149. or equivalent is filled 2,000,000 times with output sent to ``/dev/null``; for
  150. further details refer to the `source
  151. <https://github.com/fmtlib/format-benchmark/blob/master/src/tinyformat-test.cc>`_.
  152. {fmt} is up to 20-30x faster than ``std::ostringstream`` and ``sprintf`` on
  153. floating-point formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
  154. and faster than `double-conversion <https://github.com/google/double-conversion>`_ and
  155. `ryu <https://github.com/ulfjack/ryu>`_:
  156. .. image:: https://user-images.githubusercontent.com/576385/
  157. 95684665-11719600-0ba8-11eb-8e5b-972ff4e49428.png
  158. :target: https://fmt.dev/unknown_mac64_clang12.0.html
  159. Compile time and code bloat
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. The script `bloat-test.py
  162. <https://github.com/fmtlib/format-benchmark/blob/master/bloat-test.py>`_
  163. from `format-benchmark <https://github.com/fmtlib/format-benchmark>`_
  164. tests compile time and code bloat for nontrivial projects.
  165. It generates 100 translation units and uses ``printf()`` or its alternative
  166. five times in each to simulate a medium sized project. The resulting
  167. executable size and compile time (Apple LLVM version 8.1.0 (clang-802.0.42),
  168. macOS Sierra, best of three) is shown in the following tables.
  169. **Optimized build (-O3)**
  170. ============= =============== ==================== ==================
  171. Method Compile Time, s Executable size, KiB Stripped size, KiB
  172. ============= =============== ==================== ==================
  173. printf 2.6 29 26
  174. printf+string 16.4 29 26
  175. iostreams 31.1 59 55
  176. {fmt} 19.0 37 34
  177. Boost Format 91.9 226 203
  178. Folly Format 115.7 101 88
  179. ============= =============== ==================== ==================
  180. As you can see, {fmt} has 60% less overhead in terms of resulting binary code
  181. size compared to iostreams and comes pretty close to ``printf``. Boost Format
  182. and Folly Format have the largest overheads.
  183. ``printf+string`` is the same as ``printf`` but with extra ``<string>``
  184. include to measure the overhead of the latter.
  185. **Non-optimized build**
  186. ============= =============== ==================== ==================
  187. Method Compile Time, s Executable size, KiB Stripped size, KiB
  188. ============= =============== ==================== ==================
  189. printf 2.2 33 30
  190. printf+string 16.0 33 30
  191. iostreams 28.3 56 52
  192. {fmt} 18.2 59 50
  193. Boost Format 54.1 365 303
  194. Folly Format 79.9 445 430
  195. ============= =============== ==================== ==================
  196. ``libc``, ``lib(std)c++`` and ``libfmt`` are all linked as shared libraries to
  197. compare formatting function overhead only. Boost Format is a
  198. header-only library so it doesn't provide any linkage options.
  199. Running the tests
  200. ~~~~~~~~~~~~~~~~~
  201. Please refer to `Building the library`__ for the instructions on how to build
  202. the library and run the unit tests.
  203. __ https://fmt.dev/latest/usage.html#building-the-library
  204. Benchmarks reside in a separate repository,
  205. `format-benchmarks <https://github.com/fmtlib/format-benchmark>`_,
  206. so to run the benchmarks you first need to clone this repository and
  207. generate Makefiles with CMake::
  208. $ git clone --recursive https://github.com/fmtlib/format-benchmark.git
  209. $ cd format-benchmark
  210. $ cmake .
  211. Then you can run the speed test::
  212. $ make speed-test
  213. or the bloat test::
  214. $ make bloat-test
  215. Migrating code
  216. --------------
  217. `clang-tidy-fmt <https://github.com/mikecrowe/clang-tidy-fmt>`_ provides clang
  218. tidy checks for converting occurrences of ``printf`` and ``fprintf`` to
  219. ``fmt::print``.
  220. Projects using this library
  221. ---------------------------
  222. * `0 A.D. <https://play0ad.com/>`_: a free, open-source, cross-platform
  223. real-time strategy game
  224. * `2GIS <https://2gis.ru/>`_: free business listings with a city map
  225. * `AMPL/MP <https://github.com/ampl/mp>`_:
  226. an open-source library for mathematical programming
  227. * `Aseprite <https://github.com/aseprite/aseprite>`_:
  228. animated sprite editor & pixel art tool
  229. * `AvioBook <https://www.aviobook.aero/en>`_: a comprehensive aircraft
  230. operations suite
  231. * `Blizzard Battle.net <https://battle.net/>`_: an online gaming platform
  232. * `Celestia <https://celestia.space/>`_: real-time 3D visualization of space
  233. * `Ceph <https://ceph.com/>`_: a scalable distributed storage system
  234. * `ccache <https://ccache.dev/>`_: a compiler cache
  235. * `ClickHouse <https://github.com/ClickHouse/ClickHouse>`_: analytical database
  236. management system
  237. * `CUAUV <https://cuauv.org/>`_: Cornell University's autonomous underwater
  238. vehicle
  239. * `Drake <https://drake.mit.edu/>`_: a planning, control, and analysis toolbox
  240. for nonlinear dynamical systems (MIT)
  241. * `Envoy <https://lyft.github.io/envoy/>`_: C++ L7 proxy and communication bus
  242. (Lyft)
  243. * `FiveM <https://fivem.net/>`_: a modification framework for GTA V
  244. * `fmtlog <https://github.com/MengRao/fmtlog>`_: a performant fmtlib-style
  245. logging library with latency in nanoseconds
  246. * `Folly <https://github.com/facebook/folly>`_: Facebook open-source library
  247. * `GemRB <https://gemrb.org/>`_: a portable open-source implementation of
  248. Bioware’s Infinity Engine
  249. * `Grand Mountain Adventure
  250. <https://store.steampowered.com/app/1247360/Grand_Mountain_Adventure/>`_:
  251. a beautiful open-world ski & snowboarding game
  252. * `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
  253. Player vs Player Gaming Network with tweaks
  254. * `KBEngine <https://github.com/kbengine/kbengine>`_: an open-source MMOG server
  255. engine
  256. * `Keypirinha <https://keypirinha.com/>`_: a semantic launcher for Windows
  257. * `Kodi <https://kodi.tv/>`_ (formerly xbmc): home theater software
  258. * `Knuth <https://kth.cash/>`_: high-performance Bitcoin full-node
  259. * `Microsoft Verona <https://github.com/microsoft/verona>`_:
  260. research programming language for concurrent ownership
  261. * `MongoDB <https://mongodb.com/>`_: distributed document database
  262. * `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: a small tool to
  263. generate randomized datasets
  264. * `OpenSpace <https://openspaceproject.com/>`_: an open-source
  265. astrovisualization framework
  266. * `PenUltima Online (POL) <https://www.polserver.com/>`_:
  267. an MMO server, compatible with most Ultima Online clients
  268. * `PyTorch <https://github.com/pytorch/pytorch>`_: an open-source machine
  269. learning library
  270. * `quasardb <https://www.quasardb.net/>`_: a distributed, high-performance,
  271. associative database
  272. * `Quill <https://github.com/odygrd/quill>`_: asynchronous low-latency logging library
  273. * `QKW <https://github.com/ravijanjam/qkw>`_: generalizing aliasing to simplify
  274. navigation, and executing complex multi-line terminal command sequences
  275. * `redis-cerberus <https://github.com/HunanTV/redis-cerberus>`_: a Redis cluster
  276. proxy
  277. * `redpanda <https://vectorized.io/redpanda>`_: a 10x faster Kafka® replacement
  278. for mission critical systems written in C++
  279. * `rpclib <http://rpclib.net/>`_: a modern C++ msgpack-RPC server and client
  280. library
  281. * `Salesforce Analytics Cloud
  282. <https://www.salesforce.com/analytics-cloud/overview/>`_:
  283. business intelligence software
  284. * `Scylla <https://www.scylladb.com/>`_: a Cassandra-compatible NoSQL data store
  285. that can handle 1 million transactions per second on a single server
  286. * `Seastar <http://www.seastar-project.org/>`_: an advanced, open-source C++
  287. framework for high-performance server applications on modern hardware
  288. * `spdlog <https://github.com/gabime/spdlog>`_: super fast C++ logging library
  289. * `Stellar <https://www.stellar.org/>`_: financial platform
  290. * `Touch Surgery <https://www.touchsurgery.com/>`_: surgery simulator
  291. * `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: open-source
  292. MMORPG framework
  293. * `Windows Terminal <https://github.com/microsoft/terminal>`_: the new Windows
  294. terminal
  295. `More... <https://github.com/search?q=fmtlib&type=Code>`_
  296. If you are aware of other projects using this library, please let me know
  297. by `email <mailto:victor.zverovich@gmail.com>`_ or by submitting an
  298. `issue <https://github.com/fmtlib/fmt/issues>`_.
  299. Motivation
  300. ----------
  301. So why yet another formatting library?
  302. There are plenty of methods for doing this task, from standard ones like
  303. the printf family of function and iostreams to Boost Format and FastFormat
  304. libraries. The reason for creating a new library is that every existing
  305. solution that I found either had serious issues or didn't provide
  306. all the features I needed.
  307. printf
  308. ~~~~~~
  309. The good thing about ``printf`` is that it is pretty fast and readily available
  310. being a part of the C standard library. The main drawback is that it
  311. doesn't support user-defined types. ``printf`` also has safety issues although
  312. they are somewhat mitigated with `__attribute__ ((format (printf, ...))
  313. <https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
  314. There is a POSIX extension that adds positional arguments required for
  315. `i18n <https://en.wikipedia.org/wiki/Internationalization_and_localization>`_
  316. to ``printf`` but it is not a part of C99 and may not be available on some
  317. platforms.
  318. iostreams
  319. ~~~~~~~~~
  320. The main issue with iostreams is best illustrated with an example:
  321. .. code:: c++
  322. std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";
  323. which is a lot of typing compared to printf:
  324. .. code:: c++
  325. printf("%.2f\n", 1.23456);
  326. Matthew Wilson, the author of FastFormat, called this "chevron hell". iostreams
  327. don't support positional arguments by design.
  328. The good part is that iostreams support user-defined types and are safe although
  329. error handling is awkward.
  330. Boost Format
  331. ~~~~~~~~~~~~
  332. This is a very powerful library which supports both ``printf``-like format
  333. strings and positional arguments. Its main drawback is performance. According to
  334. various benchmarks, it is much slower than other methods considered here. Boost
  335. Format also has excessive build times and severe code bloat issues (see
  336. `Benchmarks`_).
  337. FastFormat
  338. ~~~~~~~~~~
  339. This is an interesting library which is fast, safe and has positional arguments.
  340. However, it has significant limitations, citing its author:
  341. Three features that have no hope of being accommodated within the
  342. current design are:
  343. * Leading zeros (or any other non-space padding)
  344. * Octal/hexadecimal encoding
  345. * Runtime width/alignment specification
  346. It is also quite big and has a heavy dependency, STLSoft, which might be too
  347. restrictive for using it in some projects.
  348. Boost Spirit.Karma
  349. ~~~~~~~~~~~~~~~~~~
  350. This is not really a formatting library but I decided to include it here for
  351. completeness. As iostreams, it suffers from the problem of mixing verbatim text
  352. with arguments. The library is pretty fast, but slower on integer formatting
  353. than ``fmt::format_to`` with format string compilation on Karma's own benchmark,
  354. see `Converting a hundred million integers to strings per second
  355. <http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_.
  356. License
  357. -------
  358. {fmt} is distributed under the MIT `license
  359. <https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.
  360. Documentation License
  361. ---------------------
  362. The `Format String Syntax <https://fmt.dev/latest/syntax.html>`_
  363. section in the documentation is based on the one from Python `string module
  364. documentation <https://docs.python.org/3/library/string.html#module-string>`_.
  365. For this reason the documentation is distributed under the Python Software
  366. Foundation license available in `doc/python-license.txt
  367. <https://raw.github.com/fmtlib/fmt/master/doc/python-license.txt>`_.
  368. It only applies if you distribute the documentation of {fmt}.
  369. Maintainers
  370. -----------
  371. The {fmt} library is maintained by Victor Zverovich (`vitaut
  372. <https://github.com/vitaut>`_) and Jonathan Müller (`foonathan
  373. <https://github.com/foonathan>`_) with contributions from many other people.
  374. See `Contributors <https://github.com/fmtlib/fmt/graphs/contributors>`_ and
  375. `Releases <https://github.com/fmtlib/fmt/releases>`_ for some of the names.
  376. Let us know if your contribution is not listed or mentioned incorrectly and
  377. we'll make it right.