mirror of
https://github.com/fmtlib/fmt.git
synced 2024-11-02 20:32:49 +00:00
Convert index to Markdown
This commit is contained in:
Victor Zverovich
parent
552842c4ff
commit
e721046e27
175
doc/index.md
Normal file
175
doc/index.md
Normal file
@ -0,0 +1,175 @@
|
||||
# Overview
|
||||
|
||||
**{fmt}** is an open-source formatting library providing a fast and safe
|
||||
alternative to C stdio and C++ iostreams.
|
||||
|
||||
What users say:
|
||||
|
||||
> 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.
|
||||
|
||||
## Format API {#format-api-intro}
|
||||
|
||||
The format API is similar in spirit to the C `printf` family of function
|
||||
but is safer, simpler and several times
|
||||
[faster](https://vitaut.net/posts/2020/fast-int-to-string-revisited/)
|
||||
than common standard library implementations.
|
||||
The [format string syntax](syntax) is similar to the one used by
|
||||
[str.format](https://docs.python.org/3/library/stdtypes.html#str.format)
|
||||
in Python:
|
||||
|
||||
```c++
|
||||
std::string s = fmt::format("The answer is {}.", 42);
|
||||
```
|
||||
|
||||
The `fmt::format` function returns a string \"The answer is 42.\". You
|
||||
can use `fmt::memory_buffer` to avoid constructing `std::string`:
|
||||
|
||||
```c++
|
||||
auto out = fmt::memory_buffer();
|
||||
fmt::format_to(std::back_inserter(out),
|
||||
"For a moment, {} happened.", "nothing");
|
||||
auto data = out.data(); // pointer to the formatted data
|
||||
auto size = out.size(); // size of the formatted data
|
||||
```
|
||||
|
||||
The `fmt::print` function performs formatting and writes the result to a
|
||||
stream:
|
||||
|
||||
```c++
|
||||
fmt::print(stderr, "System error code = {}\n", errno);
|
||||
```
|
||||
|
||||
If you omit the file argument the function will print to `stdout`:
|
||||
|
||||
```c++
|
||||
fmt::print("Don't {}\n", "panic");
|
||||
```
|
||||
|
||||
The format API also supports positional arguments useful for
|
||||
localization:
|
||||
|
||||
```c++
|
||||
fmt::print("I'd rather be {1} than {0}.", "right", "happy");
|
||||
```
|
||||
|
||||
You can pass named arguments with `fmt::arg`:
|
||||
|
||||
```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:
|
||||
|
||||
```c++
|
||||
using namespace fmt::literals;
|
||||
fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
|
||||
"name"_a="World", "number"_a=42);
|
||||
```
|
||||
|
||||
## Safety
|
||||
|
||||
The library is fully type safe, automatic memory management prevents
|
||||
buffer overflow, errors in format strings are reported using exceptions
|
||||
or at compile time. For example, the code
|
||||
|
||||
```c++
|
||||
fmt::format("The answer is {:d}", "forty-two");
|
||||
```
|
||||
|
||||
throws the `format_error` exception because the argument `"forty-two"`
|
||||
is a string while the format code `d` only applies to integers.
|
||||
|
||||
The code
|
||||
|
||||
```c++
|
||||
format(FMT_STRING("The answer is {:d}"), "forty-two");
|
||||
```
|
||||
|
||||
reports a compile-time error on compilers that support relaxed `constexpr`.
|
||||
See [Compile-Time Format String Checks](api#compile-time-format-string-checks)
|
||||
for details.
|
||||
|
||||
The following 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. 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 desirable.
|
||||
|
||||
## Compact Binary Code
|
||||
|
||||
The library produces compact per-call compiled code. For example
|
||||
([godbolt](https://godbolt.org/g/TZU4KF)),
|
||||
|
||||
```c++
|
||||
#include <fmt/core.h>
|
||||
|
||||
int main() {
|
||||
fmt::print("The answer is {}.", 42);
|
||||
}
|
||||
```
|
||||
|
||||
compiles to just
|
||||
|
||||
```asm
|
||||
main: # @main
|
||||
sub rsp, 24
|
||||
mov qword ptr [rsp], 42
|
||||
mov rcx, rsp
|
||||
mov edi, offset .L.str
|
||||
mov esi, 17
|
||||
mov edx, 1
|
||||
call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args)
|
||||
xor eax, eax
|
||||
add rsp, 24
|
||||
ret
|
||||
.L.str:
|
||||
.asciz "The answer is {}."
|
||||
```
|
||||
|
||||
## Portability
|
||||
|
||||
The library is highly portable and relies only on a small set of C++11
|
||||
features:
|
||||
|
||||
- variadic templates
|
||||
- type traits
|
||||
- rvalue references
|
||||
- decltype
|
||||
- trailing return types
|
||||
- deleted functions
|
||||
- alias templates
|
||||
|
||||
These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more
|
||||
recent compiler version. For older compilers use {fmt} [version
|
||||
4.x](https://github.com/fmtlib/fmt/releases/tag/4.1.0) which is
|
||||
maintained and only requires C++98.
|
||||
|
||||
The output of all formatting functions is consistent across platforms.
|
||||
For example,
|
||||
|
||||
```
|
||||
fmt::print("{}", std::numeric_limits<double>::infinity());
|
||||
```
|
||||
|
||||
always prints `inf` while the output of `printf` is platform-dependent.
|
||||
|
||||
## Ease of Use
|
||||
|
||||
{fmt} has a small self-contained code base with the core library
|
||||
consisting of just three header files and no external dependencies. A
|
||||
permissive MIT [license](https://github.com/fmtlib/fmt#license) allows
|
||||
using the library both in open-source and commercial projects.
|
||||
|
||||
<a class="btn btn-success" href="https://github.com/fmtlib/fmt">
|
||||
GitHubRepository
|
||||
</a>
|
||||
193
doc/index.rst
193
doc/index.rst
@ -1,193 +0,0 @@
|
||||
Overview
|
||||
========
|
||||
|
||||
**{fmt}** is an open-source formatting library providing a fast and safe
|
||||
alternative to C stdio and 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 <code>boost::format</code> and
|
||||
<code>loki::SPrintf</code>, and neither felt like the right answer.
|
||||
This does.
|
||||
</div>
|
||||
</div>
|
||||
|
||||
.. _format-api-intro:
|
||||
|
||||
Format API
|
||||
----------
|
||||
|
||||
The format API is similar in spirit to the C ``printf`` family of function but
|
||||
is safer, simpler and several times `faster
|
||||
<https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
|
||||
than common standard library implementations.
|
||||
The `format string syntax <syntax.html>`_ is similar to the one used by
|
||||
`str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_ in
|
||||
Python:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
std::string s = fmt::format("The answer is {}.", 42);
|
||||
|
||||
The ``fmt::format`` function returns a string "The answer is 42.". You can use
|
||||
``fmt::memory_buffer`` to avoid constructing ``std::string``:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
auto out = fmt::memory_buffer();
|
||||
fmt::format_to(std::back_inserter(out),
|
||||
"For a moment, {} happened.", "nothing");
|
||||
auto data = out.data(); // pointer to the formatted data
|
||||
auto size = out.size(); // size of the formatted data
|
||||
|
||||
The ``fmt::print`` function performs formatting and writes the result to a stream:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
fmt::print(stderr, "System error code = {}\n", errno);
|
||||
|
||||
If you omit the file argument the function will print to ``stdout``:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
fmt::print("Don't {}\n", "panic");
|
||||
|
||||
The format API also supports positional arguments useful for localization:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
fmt::print("I'd rather be {1} than {0}.", "right", "happy");
|
||||
|
||||
You can pass named arguments with ``fmt::arg``:
|
||||
|
||||
.. 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++
|
||||
|
||||
using namespace fmt::literals;
|
||||
fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
|
||||
"name"_a="World", "number"_a=42);
|
||||
|
||||
.. _safety:
|
||||
|
||||
Safety
|
||||
------
|
||||
|
||||
The library is fully type safe, automatic memory management prevents buffer
|
||||
overflow, errors in format strings are reported using exceptions or at compile
|
||||
time. For example, the code
|
||||
|
||||
.. code:: c++
|
||||
|
||||
fmt::format("The answer is {:d}", "forty-two");
|
||||
|
||||
throws the ``format_error`` exception because the argument ``"forty-two"`` is a
|
||||
string while the format code ``d`` only applies to integers.
|
||||
|
||||
The code
|
||||
|
||||
.. code:: c++
|
||||
|
||||
format(FMT_STRING("The answer is {:d}"), "forty-two");
|
||||
|
||||
reports a compile-time error on compilers that support relaxed ``constexpr``.
|
||||
See `here <api.html#compile-time-format-string-checks>`_ for details.
|
||||
|
||||
The following 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. 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 desirable.
|
||||
|
||||
Compact Binary Code
|
||||
-------------------
|
||||
|
||||
The library produces compact per-call compiled code. For example
|
||||
(`godbolt <https://godbolt.org/g/TZU4KF>`_),
|
||||
|
||||
.. code:: c++
|
||||
|
||||
#include <fmt/core.h>
|
||||
|
||||
int main() {
|
||||
fmt::print("The answer is {}.", 42);
|
||||
}
|
||||
|
||||
compiles to just
|
||||
|
||||
.. code:: asm
|
||||
|
||||
main: # @main
|
||||
sub rsp, 24
|
||||
mov qword ptr [rsp], 42
|
||||
mov rcx, rsp
|
||||
mov edi, offset .L.str
|
||||
mov esi, 17
|
||||
mov edx, 1
|
||||
call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args)
|
||||
xor eax, eax
|
||||
add rsp, 24
|
||||
ret
|
||||
.L.str:
|
||||
.asciz "The answer is {}."
|
||||
|
||||
.. _portability:
|
||||
|
||||
Portability
|
||||
-----------
|
||||
|
||||
The library is highly portable and relies only on a small set of C++11 features:
|
||||
|
||||
* variadic templates
|
||||
* type traits
|
||||
* rvalue references
|
||||
* decltype
|
||||
* trailing return types
|
||||
* deleted functions
|
||||
* alias templates
|
||||
|
||||
These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more recent
|
||||
compiler version. For older compilers use {fmt} `version 4.x
|
||||
<https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which is maintained and
|
||||
only requires C++98.
|
||||
|
||||
The output of all formatting functions is consistent across platforms.
|
||||
For example,
|
||||
|
||||
.. code::
|
||||
|
||||
fmt::print("{}", std::numeric_limits<double>::infinity());
|
||||
|
||||
always prints ``inf`` while the output of ``printf`` is platform-dependent.
|
||||
|
||||
.. _ease-of-use:
|
||||
|
||||
Ease of Use
|
||||
-----------
|
||||
|
||||
{fmt} has a small self-contained code base with the core library consisting of
|
||||
just three header files and no external dependencies.
|
||||
A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows
|
||||
using the library both in open-source and commercial projects.
|
||||
|
||||
`Learn more... <contents.html>`_
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
|
||||
Loading…
Reference in New Issue
Block a user