diff --git a/doc/api.rst b/doc/api.rst index 0eeab744..8bf71c57 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -164,6 +164,10 @@ Utilities System errors ------------- +fmt does not use ``errno`` to communicate errors to the user, but it may call +system functions which set ``errno``. Users should not make any assumptions about +the value of ``errno`` being preserved by library functions. + .. doxygenclass:: fmt::system_error :members: diff --git a/doc/index.rst b/doc/index.rst index ac463062..17d6b4bb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,8 +2,7 @@ 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. +It can be used as a fast and safe alternative to printf and IOStreams. .. raw:: html @@ -30,9 +29,9 @@ in Python: .. code:: c++ - fmt::format("The answer is {}", 42); + fmt::format("The answer is {}.", 42); -The ``fmt::format`` function returns a string "The answer is 42". You can use +The ``fmt::format`` function returns a string "The answer is 42.". You can use ``fmt::memory_buffer`` to avoid constructing ``std::string``: .. code:: c++ @@ -94,19 +93,25 @@ 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 +overflow, errors in format strings are reported using exceptions or at compile +tim. For example, the code .. code:: c++ fmt::format("The answer is {:d}", "forty-two"); -throws a ``format_error`` 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. +throws a ``format_error`` 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, while -Where possible, errors are caught at compile time. For example, the code +.. code:: c++ + + format(fmt("The answer is {:d}"), "forty-two"); + +reports a compile-time error for the same reason on compilers that support +relaxed ``constexpr``. + +The following code .. code:: c++ @@ -124,16 +129,10 @@ 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. -Note that fmt does not use the value of the ``errno`` global to communicate -errors to the user, but it may call system functions which set ``errno``. Since -fmt does not attempt to preserve the value of ``errno``, users should not make -any assumptions about it and always set it to ``0`` before making any system -calls that convey error information via ``errno``. - Compact binary code ------------------- -Each call to a formatting function results in a compact binary code. For example +The library is designed to produce compact per-call compiled code. For example (`godbolt `_), .. code:: c++ @@ -167,33 +166,19 @@ compiles to just 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: +The library is highly portable and relies only on a small set of C++11 features: -* 64-bit (amd64) GNU/Linux with GCC 4.4.3, - `4.6.3 `_, 4.7.2, 4.8.1, and Intel C++ - Compiler (ICC) 14.0.2 +* variadic templates +* type traits +* rvalue references +* decltype +* trailing return types +* deleted functions -* 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 `_ - -* 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``. +These are available since GCC 4.4, Clang 2.9 and MSVC 18.0 (2013). For older +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 @@ -211,7 +196,7 @@ Ease of Use ----------- fmt has a small self-contained code base with the core library consisting of -a single header file and a single source file and no external dependencies. +just three header files and no external dependencies. A permissive BSD `license `_ allows using the library both in open-source and commercial projects.