mirror of
https://github.com/fmtlib/fmt.git
synced 2024-10-04 13:59:43 +00:00
Improve docs
This commit is contained in:
Victor Zverovich
parent
2392367efc
commit
c636967c5c
62
doc/index.md
62
doc/index.md
@ -11,10 +11,10 @@ hide:
|
|||||||
<div class="feature">
|
<div class="feature">
|
||||||
<h2>Safety</h2>
|
<h2>Safety</h2>
|
||||||
<p>
|
<p>
|
||||||
Inspired by the Python's formatting facility, {fmt} provides a safe
|
Inspired by Python's formatting facility, {fmt} provides a safe replacement
|
||||||
replacement for the <code>printf</code> family of functions. Errors in format
|
for the <code>printf</code> family of functions. Errors in format strings,
|
||||||
strings, which are a common source of vulnerabilities in C, are <b>reported
|
which are a common source of vulnerabilities in C, are <b>reported at
|
||||||
at compile time</b>. For example:
|
compile time</b>. For example:
|
||||||
|
|
||||||
<pre><code class="language-cpp"
|
<pre><code class="language-cpp"
|
||||||
>fmt::format("{:d}", "I am not a number");</code></pre>
|
>fmt::format("{:d}", "I am not a number");</code></pre>
|
||||||
@ -30,9 +30,8 @@ hide:
|
|||||||
<div class="feature">
|
<div class="feature">
|
||||||
<h2>Extensibility</h2>
|
<h2>Extensibility</h2>
|
||||||
<p>
|
<p>
|
||||||
Formatting of most <b>standard types</b> including all containers, dates and
|
Formatting of most <b>standard types</b>, including all containers, dates,
|
||||||
times is <b>supported out-of-the-box</b>.
|
and times is <b>supported out-of-the-box</b>. For example:
|
||||||
For example:
|
|
||||||
|
|
||||||
<pre><code class="language-cpp"
|
<pre><code class="language-cpp"
|
||||||
>fmt::print("{}", std::vector{1, 2, 3});</code></pre>
|
>fmt::print("{}", std::vector{1, 2, 3});</code></pre>
|
||||||
@ -51,12 +50,12 @@ hide:
|
|||||||
<h2>Performance</h2>
|
<h2>Performance</h2>
|
||||||
<p>
|
<p>
|
||||||
{fmt} can be anywhere from <b>tens of percent to 20-30 times faster</b> than
|
{fmt} can be anywhere from <b>tens of percent to 20-30 times faster</b> than
|
||||||
iostreams and <code>sprintf</code>, especially on numeric formatting.
|
iostreams and <code>sprintf</code>, especially for numeric formatting.
|
||||||
|
|
||||||
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="20 0 550 300" aria-label="A chart." style="overflow: hidden;"><defs id="_ABSTRACT_RENDERER_ID_0"><clipPath id="_ABSTRACT_RENDERER_ID_1"><rect x="120" y="45" width="560" height="210"></rect></clipPath></defs><rect x="0" y="0" width="800" height="300" stroke="none" stroke-width="0" fill="#ffffff"></rect><g><text text-anchor="start" x="120" y="27.05" font-family="Arial" font-size="13" font-weight="bold" stroke="none" stroke-width="0" fill="#000000">double to string</text><rect x="120" y="16" width="560" height="13" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect></g><g><rect x="120" y="45" width="560" height="210" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect><g clip-path="url(#_ABSTRACT_RENDERER_ID_1)"><g><rect x="120" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="213" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="306" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="400" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="493" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="586" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="679" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect></g><g><rect x="121" y="53" width="450" height="26" stroke="#ff9900" stroke-width="1" fill="#ff9900"></rect><rect x="121" y="95" width="421" height="26" stroke="#109618" stroke-width="1" fill="#109618"></rect><rect x="121" y="137" width="341" height="26" stroke="#990099" stroke-width="1" fill="#990099"></rect><rect x="121" y="179" width="31" height="26" stroke="#3366cc" stroke-width="1" fill="#3366cc"></rect><rect x="121" y="221" width="15" height="26" stroke="#dc3912" stroke-width="1" fill="#dc3912"></rect></g><g><rect x="120" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#333333"></rect></g></g><g></g><g><g><text text-anchor="middle" x="120.5" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">0</text></g><g><text text-anchor="middle" x="213.6667" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">250</text></g><g><text text-anchor="middle" x="306.8333" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">500</text></g><g><text text-anchor="middle" x="400" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">750</text></g><g><text text-anchor="middle" x="493.1667" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,000</text></g><g><text text-anchor="middle" x="586.3333" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,250</text></g><g><text text-anchor="middle" x="679.5" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,500</text></g><g><text text-anchor="end" x="107" y="70.95" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">ostringstream</text></g><g><text text-anchor="end" x="107" y="112.74999999999999" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">ostrstream</text></g><g><text text-anchor="end" x="107" y="154.55" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">sprintf</text></g><g><text text-anchor="end" x="107" y="196.35" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">doubleconv</text></g><g><text text-anchor="end" x="107" y="238.15" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">fmt</text></g></g></g><g><g><text text-anchor="middle" x="300" y="291.71666666666664" font-family="Arial" font-size="13" font-style="italic" stroke="none" stroke-width="0" fill="#222222">Time (ns), smaller is better</text><rect x="120" y="280.66666666666663" width="560" height="13" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect></g></g><g></g></svg>
|
<img src="perf.svg">
|
||||||
|
|
||||||
The library <b>minimizes dynamic memory allocations</b> and can optionally
|
The library <b>minimizes dynamic memory allocations</b> and can optionally
|
||||||
<a href="api#compile-api">compile format strings</a> to optimal code.
|
<a href="api#compile-api">compile format strings</a> to optimal code.
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
@ -69,11 +68,11 @@ The library <b>minimizes dynamic memory allocations</b> and can optionally
|
|||||||
<pre><code class="language-cpp"
|
<pre><code class="language-cpp"
|
||||||
>fmt::print("Слава Україні!");</code></pre>
|
>fmt::print("Слава Україні!");</code></pre>
|
||||||
|
|
||||||
will be printed correctly on Linux, macOS and even Windows console regardless
|
will be printed correctly on Linux, macOS, and even Windows console,
|
||||||
of the codepages.
|
regardless of the codepages.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
The default is <b>locale-independent</b> but you can opt into localized
|
The default is <b>locale-independent</b>, but you can opt into localized
|
||||||
formatting and {fmt} makes it work with Unicode, working around problems in
|
formatting and {fmt} makes it work with Unicode, working around problems in
|
||||||
the standard libary.
|
the standard libary.
|
||||||
</p>
|
</p>
|
||||||
@ -89,8 +88,8 @@ The library <b>minimizes dynamic memory allocations</b> and can optionally
|
|||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Code using {fmt} is usually several times faster to compile than the
|
Code using {fmt} is usually several times faster to compile than the
|
||||||
equivalent iostreams code and while <code>printf</code> compiles faster still,
|
equivalent iostreams code, and while <code>printf</code> compiles faster
|
||||||
the gap is narrowing.
|
still, the gap is narrowing.
|
||||||
</p>
|
</p>
|
||||||
<a href="https://github.com/fmtlib/fmt?tab=readme-ov-file#compile-time-and-code-bloat">
|
<a href="https://github.com/fmtlib/fmt?tab=readme-ov-file#compile-time-and-code-bloat">
|
||||||
→ Learn more</a>
|
→ Learn more</a>
|
||||||
@ -99,34 +98,34 @@ The library <b>minimizes dynamic memory allocations</b> and can optionally
|
|||||||
<div class="feature">
|
<div class="feature">
|
||||||
<h2>Small binary footprint</h2>
|
<h2>Small binary footprint</h2>
|
||||||
<p>
|
<p>
|
||||||
Type erasure is also used to prevent template bloat resulting in <b>compact
|
Type erasure is also used to prevent template bloat, resulting in <b>compact
|
||||||
per-call binary code</b>. For example, a call to <code>fmt::print</code> with
|
per-call binary code</b>. For example, a call to <code>fmt::print</code> with
|
||||||
a single argument is less than <a href="https://godbolt.org/g/TZU4KF">ten
|
a single argument is fewer than <a href="https://godbolt.org/g/TZU4KF">ten
|
||||||
x86-64 instructions</a>, comparable to <code>printf</code> despite adding
|
x86-64 instructions</a>, comparable to <code>printf</code> despite adding
|
||||||
runtime safety and much smaller than the equivalent iostreams code.
|
runtime safety and much smaller than the equivalent iostreams code.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
The library itself has small binary footprint and some components such as
|
The library itself has small binary footprint and some components such as
|
||||||
floating-point formatting can be disabled to make it even smaller for
|
floating-point formatting can be disabled to make it even smaller for
|
||||||
resource constrained devices.
|
resource-constrained devices.
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div class="feature">
|
<div class="feature">
|
||||||
<h2>Portability</h2>
|
<h2>Portability</h2>
|
||||||
<p>
|
<p>
|
||||||
{fmt} has a <b>small self-contained codebase</b> with the core consisting of
|
{fmt} has a <b>small self-contained codebase</b> with the core consisting of
|
||||||
just three header files and no external dependencies.
|
just three header files and no external dependencies.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
The library is highly portable and requires only on a minimal <b>subset of
|
The library is highly portable and requires only a minimal <b>subset of
|
||||||
C++11</b> features which are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015)
|
C++11</b> features which are available in GCC 4.8, Clang 3.4, MSVC 19.0
|
||||||
and later. Newer compiler and standard library features are used if available
|
(2015) and later. Newer compiler and standard library features are used
|
||||||
and enable additional functionality.
|
if available, and enable additional functionality.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Where possible, the output of formatting functions is <b>consistent across
|
Where possible, the output of formatting functions is <b>consistent across
|
||||||
platforms</b>.
|
platforms</b>.
|
||||||
</p>
|
</p>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
@ -134,12 +133,13 @@ platforms</b>.
|
|||||||
<div class="feature">
|
<div class="feature">
|
||||||
<h2>Open source</h2>
|
<h2>Open source</h2>
|
||||||
<p>
|
<p>
|
||||||
{fmt} is in top hundred open-source libraries on GitHub and has <b>hundreds of
|
{fmt} is in the top hundred open-source C++ libraries on GitHub and has
|
||||||
all-time contributors</b>.
|
<a href="https://github.com/fmtlib/fmt/graphs/contributors">hundreds of
|
||||||
|
all-time contributors</a>.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Permissive MIT <a href="https://github.com/fmtlib/fmt#license">license</a>
|
The permissive MIT <a href="https://github.com/fmtlib/fmt#license">license</a>
|
||||||
allows using the library both in open-source and commercial projects.
|
allows the use the library in both open-source and commercial projects.
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
|||||||
1
doc/perf.svg
Normal file
1
doc/perf.svg
Normal file
@ -0,0 +1 @@
|
|||||||
|
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="20 0 550 300" aria-label="A chart." style="overflow: hidden;"><defs id="_ABSTRACT_RENDERER_ID_0"><clipPath id="_ABSTRACT_RENDERER_ID_1"><rect x="120" y="45" width="560" height="210"></rect></clipPath></defs><rect x="0" y="0" width="800" height="300" stroke="none" stroke-width="0" fill="#ffffff"></rect><g><text text-anchor="start" x="120" y="27.05" font-family="Arial" font-size="13" font-weight="bold" stroke="none" stroke-width="0" fill="#000000">double to string</text><rect x="120" y="16" width="560" height="13" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect></g><g><rect x="120" y="45" width="560" height="210" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect><g clip-path="url(#_ABSTRACT_RENDERER_ID_1)"><g><rect x="120" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="213" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="306" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="400" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="493" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="586" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="679" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect></g><g><rect x="121" y="53" width="450" height="26" stroke="#ff9900" stroke-width="1" fill="#ff9900"></rect><rect x="121" y="95" width="421" height="26" stroke="#109618" stroke-width="1" fill="#109618"></rect><rect x="121" y="137" width="341" height="26" stroke="#990099" stroke-width="1" fill="#990099"></rect><rect x="121" y="179" width="31" height="26" stroke="#3366cc" stroke-width="1" fill="#3366cc"></rect><rect x="121" y="221" width="15" height="26" stroke="#dc3912" stroke-width="1" fill="#dc3912"></rect></g><g><rect x="120" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#333333"></rect></g></g><g></g><g><g><text text-anchor="middle" x="120.5" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">0</text></g><g><text text-anchor="middle" x="213.6667" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">250</text></g><g><text text-anchor="middle" x="306.8333" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">500</text></g><g><text text-anchor="middle" x="400" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">750</text></g><g><text text-anchor="middle" x="493.1667" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,000</text></g><g><text text-anchor="middle" x="586.3333" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,250</text></g><g><text text-anchor="middle" x="679.5" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,500</text></g><g><text text-anchor="end" x="107" y="70.95" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">ostringstream</text></g><g><text text-anchor="end" x="107" y="112.74999999999999" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">ostrstream</text></g><g><text text-anchor="end" x="107" y="154.55" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">sprintf</text></g><g><text text-anchor="end" x="107" y="196.35" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">doubleconv</text></g><g><text text-anchor="end" x="107" y="238.15" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">fmt</text></g></g></g><g><g><text text-anchor="middle" x="300" y="291.71666666666664" font-family="Arial" font-size="13" font-style="italic" stroke="none" stroke-width="0" fill="#222222">Time (ns), smaller is better</text><rect x="120" y="280.66666666666663" width="560" height="13" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect></g></g><g></g></svg>
|
||||||
|
After Width: | Height: | Size: 4.3 KiB |
@ -30,9 +30,9 @@ markdown_extensions:
|
|||||||
- pymdownx.snippets
|
- pymdownx.snippets
|
||||||
|
|
||||||
plugins:
|
plugins:
|
||||||
|
- search
|
||||||
- mkdocstrings:
|
- mkdocstrings:
|
||||||
default_handler: cxx
|
default_handler: cxx
|
||||||
|
|
||||||
nav:
|
nav:
|
||||||
- Home: index.md
|
- Home: index.md
|
||||||
- Usage: usage.md
|
- Usage: usage.md
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user