From c636967c5ca11e621573bcbecb115f817981499f Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Tue, 4 Jun 2024 15:26:38 -0700 Subject: [PATCH] Improve docs --- doc/index.md | 62 +++++++++++++++++++++++----------------------- doc/perf.svg | 1 + support/mkdocs.yml | 2 +- 3 files changed, 33 insertions(+), 32 deletions(-) create mode 100644 doc/perf.svg diff --git a/doc/index.md b/doc/index.md index d51468a1..a619df76 100644 --- a/doc/index.md +++ b/doc/index.md @@ -11,10 +11,10 @@ hide:

Safety

- Inspired by the Python's formatting facility, {fmt} provides a safe - replacement for the printf family of functions. Errors in format - strings, which are a common source of vulnerabilities in C, are reported - at compile time. For example: + Inspired by Python's formatting facility, {fmt} provides a safe replacement + for the printf family of functions. Errors in format strings, + which are a common source of vulnerabilities in C, are reported at + compile time. For example: 

fmt::format("{:d}", "I am not a number");
@@ -30,9 +30,8 @@ hide:

Extensibility

- Formatting of most standard types including all containers, dates and - times is supported out-of-the-box. - For example: + Formatting of most standard types, including all containers, dates, + and times is supported out-of-the-box. For example: 

fmt::print("{}", std::vector{1, 2, 3});
@@ -51,12 +50,12 @@ hide:

Performance

{fmt} can be anywhere from tens of percent to 20-30 times faster than - iostreams and sprintf, especially on numeric formatting. + iostreams and sprintf, especially for numeric formatting. -double to string02505007501,0001,2501,500ostringstreamostrstreamsprintfdoubleconvfmtTime (ns), smaller is better + -The library minimizes dynamic memory allocations and can optionally -compile format strings to optimal code. + The library minimizes dynamic memory allocations and can optionally + compile format strings to optimal code.

@@ -69,11 +68,11 @@ The library minimizes dynamic memory allocations and can optionally 
fmt::print("Слава Україні!");
- will be printed correctly on Linux, macOS and even Windows console regardless - of the codepages. + will be printed correctly on Linux, macOS, and even Windows console, + regardless of the codepages.

- The default is locale-independent but you can opt into localized + The default is locale-independent, but you can opt into localized formatting and {fmt} makes it work with Unicode, working around problems in the standard libary.

@@ -89,8 +88,8 @@ The library minimizes dynamic memory allocations and can optionally

Code using {fmt} is usually several times faster to compile than the - equivalent iostreams code and while printf compiles faster still, - the gap is narrowing. + equivalent iostreams code, and while printf compiles faster + still, the gap is narrowing.

→ Learn more @@ -99,34 +98,34 @@ The library minimizes dynamic memory allocations and can optionally

Small binary footprint

- Type erasure is also used to prevent template bloat resulting in compact + Type erasure is also used to prevent template bloat, resulting in compact per-call binary code. For example, a call to fmt::print with - a single argument is less than ten + a single argument is fewer than ten x86-64 instructions, comparable to printf despite adding runtime safety and much smaller than the equivalent iostreams code.

The library itself has small binary footprint and some components such as floating-point formatting can be disabled to make it even smaller for - resource constrained devices. + resource-constrained devices.

Portability

-{fmt} has a small self-contained codebase with the core consisting of -just three header files and no external dependencies. + {fmt} has a small self-contained codebase with the core consisting of + just three header files and no external dependencies.

-The library is highly portable and requires only on a minimal subset of -C++11 features which are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) -and later. Newer compiler and standard library features are used if available -and enable additional functionality. + The library is highly portable and requires only a minimal subset of + C++11 features which are available in GCC 4.8, Clang 3.4, MSVC 19.0 + (2015) and later. Newer compiler and standard library features are used + if available, and enable additional functionality.

-Where possible, the output of formatting functions is consistent across -platforms. + Where possible, the output of formatting functions is consistent across + platforms.

@@ -134,12 +133,13 @@ platforms.

Open source

- {fmt} is in top hundred open-source libraries on GitHub and has hundreds of - all-time contributors. + {fmt} is in the top hundred open-source C++ libraries on GitHub and has + hundreds of + all-time contributors.

- Permissive MIT license - allows using the library both in open-source and commercial projects. + The permissive MIT license + allows the use the library in both open-source and commercial projects.

diff --git a/doc/perf.svg b/doc/perf.svg new file mode 100644 index 00000000..7867a154 --- /dev/null +++ b/doc/perf.svg @@ -0,0 +1 @@ +double to string02505007501,0001,2501,500ostringstreamostrstreamsprintfdoubleconvfmtTime (ns), smaller is better \ No newline at end of file diff --git a/support/mkdocs.yml b/support/mkdocs.yml index d816142e..35764023 100644 --- a/support/mkdocs.yml +++ b/support/mkdocs.yml @@ -30,9 +30,9 @@ markdown_extensions: - pymdownx.snippets plugins: + - search - mkdocstrings: default_handler: cxx - nav: - Home: index.md - Usage: usage.md