ceph/src/fmt/doc/index.rst

   1 Overview
   2 ========
   3
   4 **fmt** (formerly cppformat) is an open-source formatting library.
   5 It can be used as a fast and safe alternative to printf and IOStreams.
   6
   7 .. raw:: html
   8
   9    <div class="panel panel-default">
  10      <div class="panel-heading">What users say:</div>
  11      <div class="panel-body">
  12        Thanks for creating this library. It’s been a hole in C++ for a long
  13        time. I’ve used both boost::format and loki::SPrintf, and neither felt
  14        like the right answer. This does.
  15      </div>
  16    </div>
  17
  18 .. _format-api-intro:
  19
  20 Format API
  21 ----------
  22
  23 The replacement-based Format API provides a safe alternative to ``printf``,
  24 ``sprintf`` and friends with comparable or `better performance
  25 <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
  26 The `format string syntax <syntax.html>`_ is similar to the one used by
  27 `str.format <http://docs.python.org/3/library/stdtypes.html#str.format>`_
  28 in Python:
  29
  30 .. code:: c++
  31
  32   fmt::format("The answer is {}.", 42);
  33
  34 The ``fmt::format`` function returns a string "The answer is 42.". You can use
  35 ``fmt::memory_buffer`` to avoid constructing ``std::string``:
  36
  37 .. code:: c++
  38
  39   fmt::memory_buffer out;
  40   format_to(out, "For a moment, {} happened.", "nothing");
  41   out.data(); // returns a pointer to the formatted data
  42
  43 The ``fmt::print`` function performs formatting and writes the result to a stream:
  44
  45 .. code:: c++
  46
  47   fmt::print(stderr, "System error code = {}\n", errno);
  48
  49 The file argument can be omitted in which case the function prints to
  50 ``stdout``:
  51
  52 .. code:: c++
  53
  54   fmt::print("Don't {}\n", "panic");
  55
  56 The Format API also supports positional arguments useful for localization:
  57
  58 .. code:: c++
  59
  60   fmt::print("I'd rather be {1} than {0}.", "right", "happy");
  61
  62 Named arguments can be created with ``fmt::arg``. This makes it easier to track
  63 what goes where when multiple values are being inserted:
  64
  65 .. code:: c++
  66
  67   fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
  68              fmt::arg("name", "World"), fmt::arg("number", 42));
  69
  70 If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers
  71 an alternative, slightly terser syntax for named arguments:
  72
  73 .. code:: c++
  74
  75   fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
  76              "name"_a="World", "number"_a=42);
  77
  78 The ``_format`` suffix may be used to format string literals similar to Python:
  79
  80 .. code:: c++
  81
  82   std::string message = "{0}{1}{0}"_format("abra", "cad");
  83
  84 Other than the placement of the format string on the left of the operator,
  85 ``_format`` is functionally identical to ``fmt::format``. In order to use the
  86 literal operators, they must be made visible with the directive
  87 ``using namespace fmt::literals;``. Note that this brings in only ``_a`` and
  88 ``_format`` but nothing else from the ``fmt`` namespace.
  89
  90 .. _safety:
  91
  92 Safety
  93 ------
  94
  95 The library is fully type safe, automatic memory management prevents buffer
  96 overflow, errors in format strings are reported using exceptions or at compile
  97 time. For example, the code
  98
  99 .. code:: c++
 100
 101   fmt::format("The answer is {:d}", "forty-two");
 102
 103 throws a ``format_error`` exception with description "unknown format code 'd' for
 104 string", because the argument ``"forty-two"`` is a string while the format code
 105 ``d`` only applies to integers, while
 106
 107 .. code:: c++
 108
 109   format(fmt("The answer is {:d}"), "forty-two");
 110
 111 reports a compile-time error for the same reason on compilers that support
 112 relaxed ``constexpr``.
 113
 114 The following code
 115
 116 .. code:: c++
 117
 118   fmt::format("Cyrillic letter {}", L'\x42e');
 119
 120 produces a compile-time error because wide character ``L'\x42e'`` cannot be
 121 formatted into a narrow string. You can use a wide format string instead:
 122
 123 .. code:: c++
 124
 125   fmt::format(L"Cyrillic letter {}", L'\x42e');
 126
 127 For comparison, writing a wide character to ``std::ostream`` results in
 128 its numeric value being written to the stream (i.e. 1070 instead of letter 'ю'
 129 which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is
 130 needed.
 131
 132 Compact binary code
 133 -------------------
 134
 135 The library is designed to produce compact per-call compiled code. For example
 136 (`godbolt <https://godbolt.org/g/TZU4KF>`_),
 137
 138 .. code:: c++
 139
 140    #include <fmt/core.h>
 141
 142    int main() {
 143      fmt::print("The answer is {}.", 42);
 144    }
 145
 146 compiles to just
 147
 148 .. code:: asm
 149
 150    main: # @main
 151      sub rsp, 24
 152      mov qword ptr [rsp], 42
 153      mov rcx, rsp
 154      mov edi, offset .L.str
 155      mov esi, 17
 156      mov edx, 2
 157      call fmt::v5::vprint(fmt::v5::basic_string_view<char>, fmt::v5::format_args)
 158      xor eax, eax
 159      add rsp, 24
 160      ret
 161    .L.str:
 162      .asciz "The answer is {}."
 163
 164 .. _portability:
 165
 166 Portability
 167 -----------
 168
 169 The library is highly portable and relies only on a small set of C++11 features:
 170
 171 * variadic templates
 172 * type traits
 173 * rvalue references
 174 * decltype
 175 * trailing return types
 176 * deleted functions
 177
 178 These are available since GCC 4.4, Clang 2.9 and MSVC 18.0 (2013). For older
 179 compilers use fmt `version 4.x
 180 <https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which continues to be
 181 maintained and only requires C++98.
 182
 183 The output of all formatting functions is consistent across platforms. In
 184 particular, formatting a floating-point infinity always gives ``inf`` while the
 185 output of ``printf`` is platform-dependent in this case. For example,
 186
 187 .. code::
 188
 189   fmt::print("{}", std::numeric_limits<double>::infinity());
 190
 191 always prints ``inf``.
 192
 193 .. _ease-of-use:
 194
 195 Ease of Use
 196 -----------
 197
 198 fmt has a small self-contained code base with the core library consisting of
 199 just three header files and no external dependencies.
 200 A permissive BSD `license <https://github.com/fmtlib/fmt#license>`_ allows
 201 using the library both in open-source and commercial projects.
 202
 203 .. raw:: html
 204
 205   <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
 206
 207   <div class="section footer">
 208     <iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&amp;repo=fmt&amp;type=watch&amp;count=true"
 209             class="github-btn" width="100" height="20"></iframe>
 210   </div>