File: index.rst

package info (click to toggle)
cppformat 3.0.1%2Bds-1
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 844 kB
  • sloc: cpp: 8,205; python: 77; sh: 12; makefile: 8; ansic: 4
file content (203 lines) | stat: -rw-r--r-- 6,513 bytes parent folder | download
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
Overview
========

**fmt** (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.

.. raw:: html

   <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>

.. _format-api:

Format API
----------

The replacement-based Format API provides a safe alternative to ``printf``,
``sprintf`` and friends with comparable or `better performance
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
The `format string syntax <syntax.html>`_ is similar to the one used by
`str.format <http://docs.python.org/2/library/stdtypes.html#str.format>`_
in Python:

.. code:: c++

  fmt::format("The answer is {}", 42);
  
The ``fmt::format`` function returns a string "The answer is 42". You can use
``fmt::MemoryWriter`` to avoid constructing ``std::string``:

.. code:: c++

  fmt::MemoryWriter w;
  w.write("Look, a {} string", 'C');
  w.c_str(); // returns a C string (const char*)

The ``fmt::print`` function performs formatting and writes the result to a file:

.. code:: c++

  fmt::print(stderr, "System error code = {}\n", errno);

The file argument can be omitted in which case the function prints to
``stdout``:

.. code:: c++

  fmt::print("Don't {}\n", "panic");

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.

The Format API also supports positional arguments useful for localization:

.. code:: c++

  fmt::print("I'd rather be {1} than {0}.", "right", "happy");

Named arguments can be created with ``fmt::arg``. This makes it easier to track 
what goes where when multiple values are being inserted:

.. code:: c++

  fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
             fmt::arg("name", "World"), fmt::arg("number", 42));

If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers 
an alternative, slightly terser syntax for named arguments:

.. code:: c++

  fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
             "name"_a="World", "number"_a=42);

The ``_format`` suffix may be used to format string literals similar to Python:

.. code:: c++

  std::string message = "{0}{1}{0}"_format("abra", "cad"); 

Other than the placement of the format string on the left of the operator, 
``_format`` is functionally identical to ``fmt::format``. In order to use the 
literal operators, they must be made visible with the directive 
``using namespace fmt::literals;``. Note that this brings in only ``_a`` and 
``_format`` but nothing else from the ``fmt`` namespace.

.. _write-api:
  
Write API
---------

The concatenation-based Write API (experimental) provides a
`fast <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_
stateless alternative to IOStreams:

.. code:: c++

  fmt::MemoryWriter out;
  out << "The answer in hexadecimal is " << hex(42);

.. _safety:

Safety
------

The library is fully type safe, automatic memory management prevents buffer overflow,
errors in format strings are reported using exceptions. For example, the code

.. code:: c++

  fmt::format("The answer is {:d}", "forty-two");

throws a ``FormatError`` exception with description
"unknown format code 'd' for string", because the argument
``"forty-two"`` is a string while the format code ``d``
only applies to integers.

Where possible, errors are caught at compile time. For example, the code

.. code:: c++

  fmt::format("Cyrillic letter {}", L'\x42e');
  
produces a compile-time error because wide character ``L'\x42e'`` cannot be
formatted into a narrow string. You can use a wide format string instead:

.. code:: c++

  fmt::format(L"Cyrillic letter {}", L'\x42e');

For comparison, writing a wide character to ``std::ostream`` results in
its numeric value being written to the stream (i.e. 1070 instead of letter 'ю' which
is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is needed.

.. _portability:

Portability
-----------

The library is highly portable. Here is an incomplete list of operating systems and
compilers where it has been tested and known to work:

* 64-bit (amd64) GNU/Linux with GCC 4.4.3, `4.6.3 <https://travis-ci.org/fmtlib/fmt>`_,
  4.7.2, 4.8.1 and Intel C++ Compiler (ICC) 14.0.2

* 32-bit (i386) GNU/Linux with GCC 4.4.3, 4.6.3

* Mac OS X with GCC 4.2.1 and Clang 4.2, 5.1.0

* 64-bit Windows with Visual C++ 2010, 2013 and
  `2015 <https://ci.appveyor.com/project/vitaut/fmt>`_

* 32-bit Windows with Visual C++ 2010

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:

* 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.

* User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes 
  ``_format`` and ``_a`` are functionally equivalent to the functions 
  ``fmt::format`` and ``fmt::arg``.

The output of all formatting functions is consistent across platforms. In particular,
formatting a floating-point infinity always gives ``inf`` while the output
of ``printf`` is platform-dependent in this case. For example,

.. code::

  fmt::print("{}", std::numeric_limits<double>::infinity());

always prints ``inf``.

.. _ease-of-use:

Ease of Use
-----------

fmt has a small self-contained code base consisting of a single header file
and a single source file and no external dependencies. A permissive BSD `license
<https://github.com/fmtlib/fmt#license>`_ allows using the library both
in open-source and commercial projects.

.. raw:: html

  <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&amp;repo=fmt&amp;type=watch&amp;count=true"
            class="github-btn" width="100" height="20"></iframe>
  </div>