From ef7369ce900346f403472231b60662936b24e731 Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Thu, 28 Nov 2019 08:09:46 -0800 Subject: [PATCH] Update docs --- README.rst | 2 +- doc/_templates/layout.html | 2 +- doc/index.rst | 50 +++++++++++++++----------------------- 3 files changed, 22 insertions(+), 32 deletions(-) diff --git a/README.rst b/README.rst index 4ee80dd7..0d01227d 100644 --- a/README.rst +++ b/README.rst @@ -184,7 +184,7 @@ further details refer to the `source formatting (`dtoa-benchmark `_) and as fast as `double-conversion `_: -.. image:: https://user-images.githubusercontent.com/576385/54883977-9fe8c000-4e28-11e9-8bde-272d122e7c52.jpg +.. image:: https://user-images.githubusercontent.com/576385/69767160-cdaca400-112f-11ea-9fc5-347c9f83caad.png :target: https://fmt.dev/unknown_mac64_clang10.0.html Compile time and code bloat diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index ed19bcd3..d5f4b70d 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -84,7 +84,7 @@

{fmt}

-

Small, safe and fast formatting library

+

A modern formatting library

@@ -20,12 +21,13 @@ It can be used as a fast and safe alternative to printf and IOStreams. Format API ---------- -The replacement-based Format API provides a safe alternative to ``printf``, -``sprintf`` and friends with comparable or `better performance -`_. +The format API is similar in spirit to the C ``printf`` family of function but +is safer, simpler and serveral times `faster +`_ +than common standard library implementations. The `format string syntax `_ is similar to the one used by -`str.format `_ -in Python: +`str.format `_ in +Python: .. code:: c++ @@ -60,7 +62,7 @@ The Format API also supports positional arguments useful for localization: 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: +what goes where when multiple arguments are being formatted: .. code:: c++ @@ -72,21 +74,10 @@ 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); -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. - .. _safety: Safety @@ -106,11 +97,10 @@ string", because the argument ``"forty-two"`` is a string while the format code .. code:: c++ - format(fmt("The answer is {:d}"), "forty-two"); + format(FMT_STRING("The answer is {:d}"), "forty-two"); reports a compile-time error for the same reason on compilers that support -relaxed ``constexpr``. See `here `_ for how to enable -compile-time checks. +relaxed ``constexpr``. See `here `_ for details. The following code @@ -178,13 +168,13 @@ The library is highly portable and relies only on a small set of C++11 features: * alias templates These are available since GCC 4.8, Clang 3.0 and MSVC 19.0 (2015). For older -compilers use fmt `version 4.x +compilers use {fmt} `version 4.x `_ which continues to be maintained and only requires C++98. 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, +output of ``printf`` is platform-dependent. For example, .. code:: @@ -197,9 +187,9 @@ always prints ``inf``. Ease of Use ----------- -fmt has a small self-contained code base with the core library consisting of +{fmt} has a small self-contained code base with the core library consisting of just three header files and no external dependencies. -A permissive BSD `license `_ allows +A permissive MIT `license `_ allows using the library both in open-source and commercial projects. .. raw:: html