-
Notifications
You must be signed in to change notification settings - Fork 13
/
Copy pathindex.html
310 lines (260 loc) · 19.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Overview — fmt 4.0.0 documentation</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/breathe.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '4.0.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html',
SOURCELINK_SUFFIX: '.txt',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<meta name="description" content="Small, safe and fast formatting library">
<meta name="keywords" content="C++, formatting, printf, string, library">
<meta name="author" content="Victor Zverovich">
<link rel="stylesheet" href="_static/fmt.css">
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-20116650-4"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-20116650-4');
</script>
</head>
<body role="document">
<nav class="navbar navbar-inverse">
<div class="tb-container">
<div class="row">
<div class="navbar-content">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed"
data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">{fmt}</a>
</div>
<div class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"
role="button" aria-expanded="false">4.0.0
<span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="https://fmt.dev/10.2.0">10.2.0</a></li>
<li><a href="https://fmt.dev/10.1.1">10.1.1</a></li>
<li><a href="https://fmt.dev/10.1.0">10.1.0</a></li>
</ul>
</li>
<li><a href="contents.html">Contents</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="api.html">API</a></li>
<li><a href="syntax.html">Syntax</a></li>
</ul>
<form class="navbar-form navbar-right" role="search" action="search.html"
method="get">
<div class="form-group">
<input type="text" name="q" class="form-control"
placeholder="Search" >
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
</div>
</nav>
<div class="jumbotron">
<div class="tb-container">
<h1>{fmt}</h1>
<p class="lead">A modern formatting library</p>
<div class="btn-group" role="group">
<a class="btn btn-success"
href="https://github.com/fmtlib/fmt/releases/download/4.0.0/fmt-4.0.0.zip">
<span class="glyphicon glyphicon-download"></span> Download
</a>
</div>
</div>
</div>
<div class="tb-container">
<div class="row">
<div class="content">
<section id="overview">
<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
<p><strong>fmt</strong> (formerly cppformat) is an open-source formatting library.
It can be used as a safe alternative to printf or as a fast
alternative to C++ IOStreams.</p>
<div class="panel panel-default">
<div class="panel-heading">What users say:</div>
<div class="panel-body">
Thanks for creating this library. It’s been a hole in C++ for a long
time. I’ve used both boost::format and loki::SPrintf, and neither felt
like the right answer. This does.
</div>
</div><section id="format-api">
<span id="id1"></span><h2>Format API<a class="headerlink" href="#format-api" title="Permalink to this headline">¶</a></h2>
<p>The replacement-based Format API provides a safe alternative to <code class="docutils literal notranslate"><span class="pre">printf</span></code>,
<code class="docutils literal notranslate"><span class="pre">sprintf</span></code> and friends with comparable or <a class="reference external" href="http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html">better performance</a>.
The <a class="reference external" href="syntax.html">format string syntax</a> is similar to the one used by
<a class="reference external" href="http://docs.python.org/2/library/stdtypes.html#str.format">str.format</a>
in Python:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"The answer is {}"</span><span class="p">,</span><span class="w"> </span><span class="mi">42</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">fmt::format</span></code> function returns a string “The answer is 42”. You can use
<code class="docutils literal notranslate"><span class="pre">fmt::MemoryWriter</span></code> to avoid constructing <code class="docutils literal notranslate"><span class="pre">std::string</span></code>:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">MemoryWriter</span><span class="w"> </span><span class="n">w</span><span class="p">;</span>
<span class="n">w</span><span class="p">.</span><span class="n">write</span><span class="p">(</span><span class="s">"Look, a {} string"</span><span class="p">,</span><span class="w"> </span><span class="sc">'C'</span><span class="p">);</span>
<span class="n">w</span><span class="p">.</span><span class="n">c_str</span><span class="p">();</span><span class="w"> </span><span class="c1">// returns a C string (const char*)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">fmt::print</span></code> function performs formatting and writes the result to a file:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="n">stderr</span><span class="p">,</span><span class="w"> </span><span class="s">"System error code = {}</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span><span class="w"> </span><span class="n">errno</span><span class="p">);</span>
</pre></div>
</div>
<p>The file argument can be omitted in which case the function prints to
<code class="docutils literal notranslate"><span class="pre">stdout</span></code>:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"Don't {}</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span><span class="w"> </span><span class="s">"panic"</span><span class="p">);</span>
</pre></div>
</div>
<p>If your compiler supports C++11, then the formatting functions are implemented
with variadic templates. Otherwise variadic functions are emulated by generating
a set of lightweight wrappers. This ensures compatibility with older compilers
while providing a natural API.</p>
<p>The Format API also supports positional arguments useful for localization:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"I'd rather be {1} than {0}."</span><span class="p">,</span><span class="w"> </span><span class="s">"right"</span><span class="p">,</span><span class="w"> </span><span class="s">"happy"</span><span class="p">);</span>
</pre></div>
</div>
<p>Named arguments can be created with <code class="docutils literal notranslate"><span class="pre">fmt::arg</span></code>. This makes it easier to track
what goes where when multiple values are being inserted:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"Hello, {name}! The answer is {number}. Goodbye, {name}."</span><span class="p">,</span>
<span class="w"> </span><span class="n">fmt</span><span class="o">::</span><span class="n">arg</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span><span class="w"> </span><span class="s">"World"</span><span class="p">),</span><span class="w"> </span><span class="n">fmt</span><span class="o">::</span><span class="n">arg</span><span class="p">(</span><span class="s">"number"</span><span class="p">,</span><span class="w"> </span><span class="mi">42</span><span class="p">));</span>
</pre></div>
</div>
<p>If your compiler supports C++11 user-defined literals, the suffix <code class="docutils literal notranslate"><span class="pre">_a</span></code> offers
an alternative, slightly terser syntax for named arguments:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"Hello, {name}! The answer is {number}. Goodbye, {name}."</span><span class="p">,</span>
<span class="w"> </span><span class="s">"name"</span><span class="n">_a</span><span class="o">=</span><span class="s">"World"</span><span class="p">,</span><span class="w"> </span><span class="s">"number"</span><span class="n">_a</span><span class="o">=</span><span class="mi">42</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">_format</span></code> suffix may be used to format string literals similar to Python:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"{0}{1}{0}"</span><span class="n">_format</span><span class="p">(</span><span class="s">"abra"</span><span class="p">,</span><span class="w"> </span><span class="s">"cad"</span><span class="p">);</span>
</pre></div>
</div>
<p>Other than the placement of the format string on the left of the operator,
<code class="docutils literal notranslate"><span class="pre">_format</span></code> is functionally identical to <code class="docutils literal notranslate"><span class="pre">fmt::format</span></code>. In order to use the
literal operators, they must be made visible with the directive
<code class="docutils literal notranslate"><span class="pre">using</span> <span class="pre">namespace</span> <span class="pre">fmt::literals;</span></code>. Note that this brings in only <code class="docutils literal notranslate"><span class="pre">_a</span></code> and
<code class="docutils literal notranslate"><span class="pre">_format</span></code> but nothing else from the <code class="docutils literal notranslate"><span class="pre">fmt</span></code> namespace.</p>
</section>
<section id="write-api">
<span id="id2"></span><h2>Write API<a class="headerlink" href="#write-api" title="Permalink to this headline">¶</a></h2>
<p>The concatenation-based Write API (experimental) provides a <a class="reference external" href="http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html">fast</a>
stateless alternative to IOStreams:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">MemoryWriter</span><span class="w"> </span><span class="n">out</span><span class="p">;</span>
<span class="n">out</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">"The answer in hexadecimal is "</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="n">hex</span><span class="p">(</span><span class="mi">42</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="safety">
<span id="id3"></span><h2>Safety<a class="headerlink" href="#safety" title="Permalink to this headline">¶</a></h2>
<p>The library is fully type safe, automatic memory management prevents buffer
overflow, errors in format strings are reported using exceptions. For example,
the code</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"The answer is {:d}"</span><span class="p">,</span><span class="w"> </span><span class="s">"forty-two"</span><span class="p">);</span>
</pre></div>
</div>
<p>throws a <code class="docutils literal notranslate"><span class="pre">FormatError</span></code> exception with description
“unknown format code ‘d’ for string”, because the argument
<code class="docutils literal notranslate"><span class="pre">"forty-two"</span></code> is a string while the format code <code class="docutils literal notranslate"><span class="pre">d</span></code>
only applies to integers.</p>
<p>Where possible, errors are caught at compile time. For example, the code</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>fmt::format("Cyrillic letter {}", L'\x42e');
</pre></div>
</div>
<p>produces a compile-time error because wide character <code class="docutils literal notranslate"><span class="pre">L'\x42e'</span></code> cannot be
formatted into a narrow string. You can use a wide format string instead:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>fmt::format(L"Cyrillic letter {}", L'\x42e');
</pre></div>
</div>
<p>For comparison, writing a wide character to <code class="docutils literal notranslate"><span class="pre">std::ostream</span></code> results in
its numeric value being written to the stream (i.e. 1070 instead of letter ‘ю’
which is represented by <code class="docutils literal notranslate"><span class="pre">L'\x42e'</span></code> if we use Unicode) which is rarely what is
needed.</p>
</section>
<section id="portability">
<span id="id4"></span><h2>Portability<a class="headerlink" href="#portability" title="Permalink to this headline">¶</a></h2>
<p>The library is highly portable. Here is an incomplete list of operating systems
and compilers where it has been tested and known to work:</p>
<ul class="simple">
<li><p>64-bit (amd64) GNU/Linux with GCC 4.4.3,
<a class="reference external" href="https://travis-ci.org/fmtlib/fmt">4.6.3</a>, 4.7.2, 4.8.1, and Intel C++
Compiler (ICC) 14.0.2</p></li>
<li><p>32-bit (i386) GNU/Linux with GCC 4.4.3, 4.6.3</p></li>
<li><p>Mac OS X with GCC 4.2.1 and Clang 4.2, 5.1.0</p></li>
<li><p>64-bit Windows with Visual C++ 2010, 2013 and
<a class="reference external" href="https://ci.appveyor.com/project/vitaut/fmt">2015</a></p></li>
<li><p>32-bit Windows with Visual C++ 2010</p></li>
</ul>
<p>Although the library uses C++11 features when available, it also works with
older compilers and standard library implementations. The only thing to keep in
mind for C++98 portability:</p>
<ul class="simple">
<li><p>Variadic templates: minimum GCC 4.4, Clang 2.9 or VS2013. This feature allows
the Format API to accept an unlimited number of arguments. With older
compilers the maximum is 15.</p></li>
<li><p>User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes
<code class="docutils literal notranslate"><span class="pre">_format</span></code> and <code class="docutils literal notranslate"><span class="pre">_a</span></code> are functionally equivalent to the functions
<code class="docutils literal notranslate"><span class="pre">fmt::format</span></code> and <code class="docutils literal notranslate"><span class="pre">fmt::arg</span></code>.</p></li>
</ul>
<p>The output of all formatting functions is consistent across platforms. In
particular, formatting a floating-point infinity always gives <code class="docutils literal notranslate"><span class="pre">inf</span></code> while the
output of <code class="docutils literal notranslate"><span class="pre">printf</span></code> is platform-dependent in this case. For example,</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"{}"</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">numeric_limits</span><span class="o"><</span><span class="kt">double</span><span class="o">>::</span><span class="n">infinity</span><span class="p">());</span>
</pre></div>
</div>
<p>always prints <code class="docutils literal notranslate"><span class="pre">inf</span></code>.</p>
</section>
<section id="ease-of-use">
<span id="id7"></span><h2>Ease of Use<a class="headerlink" href="#ease-of-use" title="Permalink to this headline">¶</a></h2>
<p>fmt has a small self-contained code base with the core library consisting of
a single header file and a single source file and no external dependencies.
A permissive BSD <a class="reference external" href="https://github.com/fmtlib/fmt#license">license</a> allows
using the library both in open-source and commercial projects.</p>
<a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
<div class="section footer">
<iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true"
class="github-btn" width="100" height="20"></iframe>
</div></section>
</section>
</div>
</div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2012-present, Victor Zverovich.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.3.0.
</div>
<script src="_static/bootstrap.min.js"></script>
</body>
</html>