From e721046e2742a813ec83c1ae9a9d09b1f53318da Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Mon, 27 May 2024 20:03:30 -0700 Subject: [PATCH] Convert index to Markdown --- doc/index.md | 175 +++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 193 -------------------------------------------------- 2 files changed, 175 insertions(+), 193 deletions(-) create mode 100644 doc/index.md delete mode 100644 doc/index.rst diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 00000000..5db6a0ce --- /dev/null +++ b/doc/index.md @@ -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 + +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, 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::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. + + + GitHubRepository + diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 4e50c18d..00000000 --- a/doc/index.rst +++ /dev/null @@ -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 - -
-
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-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 -`_ -than common standard library implementations. -The `format string syntax `_ is similar to the one used by -`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 `_ 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 `_), - -.. code:: c++ - - #include - - 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, 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 -`_ 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::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 `_ allows -using the library both in open-source and commercial projects. - -`Learn more... `_ - -.. raw:: html - - GitHub Repository