index.rst 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  1. Overview
  2. ========
  3. **{fmt}** is an open-source formatting library providing a fast and safe
  4. alternative to C stdio and C++ iostreams.
  5. .. raw:: html
  6. <div class="panel panel-default">
  7. <div class="panel-heading">What users say:</div>
  8. <div class="panel-body">
  9. Thanks for creating this library. It’s been a hole in C++ for
  10. a long time. I’ve used both <code>boost::format</code> and
  11. <code>loki::SPrintf</code>, and neither felt like the right answer.
  12. This does.
  13. </div>
  14. </div>
  15. .. _format-api-intro:
  16. Format API
  17. ----------
  18. The format API is similar in spirit to the C ``printf`` family of function but
  19. is safer, simpler and several times `faster
  20. <https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
  21. than common standard library implementations.
  22. The `format string syntax <syntax.html>`_ is similar to the one used by
  23. `str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_ in
  24. Python:
  25. .. code:: c++
  26. std::string s = fmt::format("The answer is {}.", 42);
  27. The ``fmt::format`` function returns a string "The answer is 42.". You can use
  28. ``fmt::memory_buffer`` to avoid constructing ``std::string``:
  29. .. code:: c++
  30. auto out = fmt::memory_buffer();
  31. fmt::format_to(std::back_inserter(out),
  32. "For a moment, {} happened.", "nothing");
  33. auto data = out.data(); // pointer to the formatted data
  34. auto size = out.size(); // size of the formatted data
  35. The ``fmt::print`` function performs formatting and writes the result to a stream:
  36. .. code:: c++
  37. fmt::print(stderr, "System error code = {}\n", errno);
  38. If you omit the file argument the function will print to ``stdout``:
  39. .. code:: c++
  40. fmt::print("Don't {}\n", "panic");
  41. The format API also supports positional arguments useful for localization:
  42. .. code:: c++
  43. fmt::print("I'd rather be {1} than {0}.", "right", "happy");
  44. You can pass named arguments with ``fmt::arg``:
  45. .. code:: c++
  46. fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
  47. fmt::arg("name", "World"), fmt::arg("number", 42));
  48. If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers
  49. an alternative, slightly terser syntax for named arguments:
  50. .. code:: c++
  51. using namespace fmt::literals;
  52. fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
  53. "name"_a="World", "number"_a=42);
  54. .. _safety:
  55. Safety
  56. ------
  57. The library is fully type safe, automatic memory management prevents buffer
  58. overflow, errors in format strings are reported using exceptions or at compile
  59. time. For example, the code
  60. .. code:: c++
  61. fmt::format("The answer is {:d}", "forty-two");
  62. throws the ``format_error`` exception because the argument ``"forty-two"`` is a
  63. string while the format code ``d`` only applies to integers.
  64. The code
  65. .. code:: c++
  66. format(FMT_STRING("The answer is {:d}"), "forty-two");
  67. reports a compile-time error on compilers that support relaxed ``constexpr``.
  68. See `here <api.html#compile-time-format-string-checks>`_ for details.
  69. The following code
  70. .. code:: c++
  71. fmt::format("Cyrillic letter {}", L'\x42e');
  72. produces a compile-time error because wide character ``L'\x42e'`` cannot be
  73. formatted into a narrow string. For comparison, writing a wide character to
  74. ``std::ostream`` results in its numeric value being written to the stream
  75. (i.e. 1070 instead of letter 'ю' which is represented by ``L'\x42e'`` if we
  76. use Unicode) which is rarely desirable.
  77. Compact Binary Code
  78. -------------------
  79. The library produces compact per-call compiled code. For example
  80. (`godbolt <https://godbolt.org/g/TZU4KF>`_),
  81. .. code:: c++
  82. #include <fmt/core.h>
  83. int main() {
  84. fmt::print("The answer is {}.", 42);
  85. }
  86. compiles to just
  87. .. code:: asm
  88. main: # @main
  89. sub rsp, 24
  90. mov qword ptr [rsp], 42
  91. mov rcx, rsp
  92. mov edi, offset .L.str
  93. mov esi, 17
  94. mov edx, 1
  95. call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args)
  96. xor eax, eax
  97. add rsp, 24
  98. ret
  99. .L.str:
  100. .asciz "The answer is {}."
  101. .. _portability:
  102. Portability
  103. -----------
  104. The library is highly portable and relies only on a small set of C++11 features:
  105. * variadic templates
  106. * type traits
  107. * rvalue references
  108. * decltype
  109. * trailing return types
  110. * deleted functions
  111. * alias templates
  112. These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more recent
  113. compiler version. For older compilers use {fmt} `version 4.x
  114. <https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which is maintained and
  115. only requires C++98.
  116. The output of all formatting functions is consistent across platforms.
  117. For example,
  118. .. code::
  119. fmt::print("{}", std::numeric_limits<double>::infinity());
  120. always prints ``inf`` while the output of ``printf`` is platform-dependent.
  121. .. _ease-of-use:
  122. Ease of Use
  123. -----------
  124. {fmt} has a small self-contained code base with the core library consisting of
  125. just three header files and no external dependencies.
  126. A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows
  127. using the library both in open-source and commercial projects.
  128. `Learn more... <contents.html>`_
  129. .. raw:: html
  130. <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
  131. <div class="section footer">
  132. <iframe src="https://ghbtns.com/github-btn.html?user=fmtlib&amp;repo=fmt&amp;type=watch&amp;count=true"
  133. class="github-btn" width="100" height="20"></iframe>
  134. </div>