Mercurial > minori

comparison dep/fmt/doc/index.rst @ 343:1faa72660932

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: transfer back to cmake from autotools autotools just made lots of things more complicated than they should have and many things broke (i.e. translations)
author Paper <paper@paper.us.eu.org>
date Thu, 20 Jun 2024 05:56:06 -0400
parents
children
comparison
equal deleted inserted replaced
342:adb79bdde329 343:1faa72660932
1 Overview
2 ========
3
4 **{fmt}** is an open-source formatting library providing a fast and safe
5 alternative to C stdio and C++ 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
13 a long time. I’ve used both <code>boost::format</code> and
14 <code>loki::SPrintf</code>, and neither felt like the right answer.
15 This does.
16 </div>
17 </div>
18
19 .. _format-api-intro:
20
21 Format API
22 ----------
23
24 The format API is similar in spirit to the C ``printf`` family of function but
25 is safer, simpler and several times `faster
26 <https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
27 than common standard library implementations.
28 The `format string syntax <syntax.html>`_ is similar to the one used by
29 `str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_ in
30 Python:
31
32 .. code:: c++
33
34 std::string s = fmt::format("The answer is {}.", 42);
35
36 The ``fmt::format`` function returns a string "The answer is 42.". You can use
37 ``fmt::memory_buffer`` to avoid constructing ``std::string``:
38
39 .. code:: c++
40
41 auto out = fmt::memory_buffer();
42 fmt::format_to(std::back_inserter(out),
43 "For a moment, {} happened.", "nothing");
44 auto data = out.data(); // pointer to the formatted data
45 auto size = out.size(); // size of the formatted data
46
47 The ``fmt::print`` function performs formatting and writes the result to a stream:
48
49 .. code:: c++
50
51 fmt::print(stderr, "System error code = {}\n", errno);
52
53 If you omit the file argument the function will print to ``stdout``:
54
55 .. code:: c++
56
57 fmt::print("Don't {}\n", "panic");
58
59 The format API also supports positional arguments useful for localization:
60
61 .. code:: c++
62
63 fmt::print("I'd rather be {1} than {0}.", "right", "happy");
64
65 You can pass named arguments with ``fmt::arg``:
66
67 .. code:: c++
68
69 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
70 fmt::arg("name", "World"), fmt::arg("number", 42));
71
72 If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers
73 an alternative, slightly terser syntax for named arguments:
74
75 .. code:: c++
76
77 using namespace fmt::literals;
78 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
79 "name"_a="World", "number"_a=42);
80
81 .. _safety:
82
83 Safety
84 ------
85
86 The library is fully type safe, automatic memory management prevents buffer
87 overflow, errors in format strings are reported using exceptions or at compile
88 time. For example, the code
89
90 .. code:: c++
91
92 fmt::format("The answer is {:d}", "forty-two");
93
94 throws the ``format_error`` exception because the argument ``"forty-two"`` is a
95 string while the format code ``d`` only applies to integers.
96
97 The code
98
99 .. code:: c++
100
101 format(FMT_STRING("The answer is {:d}"), "forty-two");
102
103 reports a compile-time error on compilers that support relaxed ``constexpr``.
104 See `here <api.html#compile-time-format-string-checks>`_ for details.
105
106 The following code
107
108 .. code:: c++
109
110 fmt::format("Cyrillic letter {}", L'\x42e');
111
112 produces a compile-time error because wide character ``L'\x42e'`` cannot be
113 formatted into a narrow string. For comparison, writing a wide character to
114 ``std::ostream`` results in its numeric value being written to the stream
115 (i.e. 1070 instead of letter 'ю' which is represented by ``L'\x42e'`` if we
116 use Unicode) which is rarely desirable.
117
118 Compact Binary Code
119 -------------------
120
121 The library produces compact per-call compiled code. For example
122 (`godbolt <https://godbolt.org/g/TZU4KF>`_),
123
124 .. code:: c++
125
126 #include <fmt/core.h>
127
128 int main() {
129 fmt::print("The answer is {}.", 42);
130 }
131
132 compiles to just
133
134 .. code:: asm
135
136 main: # @main
137 sub rsp, 24
138 mov qword ptr [rsp], 42
139 mov rcx, rsp
140 mov edi, offset .L.str
141 mov esi, 17
142 mov edx, 1
143 call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args)
144 xor eax, eax
145 add rsp, 24
146 ret
147 .L.str:
148 .asciz "The answer is {}."
149
150 .. _portability:
151
152 Portability
153 -----------
154
155 The library is highly portable and relies only on a small set of C++11 features:
156
157 * variadic templates
158 * type traits
159 * rvalue references
160 * decltype
161 * trailing return types
162 * deleted functions
163 * alias templates
164
165 These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more recent
166 compiler version. For older compilers use {fmt} `version 4.x
167 <https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which is maintained and
168 only requires C++98.
169
170 The output of all formatting functions is consistent across platforms.
171 For example,
172
173 .. code::
174
175 fmt::print("{}", std::numeric_limits<double>::infinity());
176
177 always prints ``inf`` while the output of ``printf`` is platform-dependent.
178
179 .. _ease-of-use:
180
181 Ease of Use
182 -----------
183
184 {fmt} has a small self-contained code base with the core library consisting of
185 just three header files and no external dependencies.
186 A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows
187 using the library both in open-source and commercial projects.
188
189 `Learn more... <contents.html>`_
190
191 .. raw:: html
192
193 <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
194
195 <div class="section footer">
196 <iframe src="https://ghbtns.com/github-btn.html?user=fmtlib&amp;repo=fmt&amp;type=watch&amp;count=true"
197 class="github-btn" width="100" height="20"></iframe>
198 </div>