diff --git a/doc/fmt.css b/doc/fmt.css index d9d34b3c..3ad561d6 100644 --- a/doc/fmt.css +++ b/doc/fmt.css @@ -9,3 +9,33 @@ .docblock-desc { margin-left: 1em; } + +.features-container { + display: flex; + flex-wrap: wrap; + gap: 20px; + justify-content: center; /* Center the items horizontally */ +} + +.feature { + flex: 1 1 calc(50% - 20px); /* Two columns with space between */ + max-width: 600px; /* Set the maximum width for the feature boxes */ + box-sizing: border-box; + padding: 10px; + overflow: hidden; /* Hide overflow content */ + text-overflow: ellipsis; /* Handle text overflow */ + white-space: normal; /* Allow text wrapping */ +} + +.feature h2 { + margin-top: 0px; + font-weight: bold; +} + +@media (max-width: 768px) { + .feature { + flex: 1 1 100%; /* Stack columns on smaller screens */ + max-width: 100%; /* Allow full width on smaller screens */ + white-space: normal; /* Allow text wrapping on smaller screens */ + } +} diff --git a/doc/index.md b/doc/index.md index 3c4c1037..24b334d8 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,175 +1,146 @@ -# Overview +--- +hide: + - navigation + - toc +--- -**{fmt}** is an open-source formatting library providing a fast and safe -alternative to C stdio and C++ iostreams. +# A modern formatting library -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. +
+

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: -## Format API + 

fmt::format("The answer is {:d}", "forty-two");
-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.md) is similar to the one used by -[str.format](https://docs.python.org/3/library/stdtypes.html#str.format) -in Python: + will give a compile-time error because d is not a valid + format specifier for strings. APIs like + fmt::format prevent buffer overflow errors via + automatic memory management. +

+→ Learn more +
-```c++ -std::string s = fmt::format("The answer is {}.", 42); -``` +
+

Extensibility

+

+ 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});
-The `fmt::format` function returns a string \"The answer is 42.\". You -can use `fmt::memory_buffer` to avoid constructing `std::string`: + prints the vector in a JSON-like format: -```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 -``` + 
[1, 2, 3]
-The `fmt::print` function performs formatting and writes the result to a -stream: + You can make your own types formattable and even make compile-time + checks work for them. +

+→ Learn more +
-```c++ -fmt::print(stderr, "System error code = {}\n", errno); -``` +
+

Performance

+

+ {fmt} can be anywhere from tens of percent to 20-30 times faster than + iostreams and sprintf, especially on numeric formatting. -If you omit the file argument the function will print to `stdout`: +double to string02505007501,0001,2501,500ostringstreamostrstreamsprintfdoubleconvfmtTime (ns), smaller is better -```c++ -fmt::print("Don't {}\n", "panic"); -``` +The library minimizes dynamic memory allocations and allows +format string compilation. +

+
-The format API also supports positional arguments useful for -localization: +
+

Unicode support

+

+ {fmt} provides portable Unicode support on major operating systems + with UTF-8 and normal char strings. For example: -```c++ -fmt::print("I'd rather be {1} than {0}.", "right", "happy"); -``` + 

fmt::print("Слава Україні!");
-You can pass named arguments with `fmt::arg`: + 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 + formatting and {fmt} makes it work with Unicode, working around problems in + the standard libary. +

+
-```c++ -fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", - fmt::arg("name", "World"), fmt::arg("number", 42)); -``` +
+

Fast compilation

+

+ The library makes extensive use of type erasure to achieve fast + compilation. fmt/base.h provides a subset + of the API with minimal include dependencies and enough functionality + to replace all uses of *printf. +

+

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

+ +→ Learn more +
-If your compiler supports C++11 user-defined literals, the suffix `_a` -offers an alternative, slightly terser syntax for named arguments: +
+

Small binary footprint

+

+ 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 + 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. +

+
-```c++ -using namespace fmt::literals; -fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", - "name"_a="World", "number"_a=42); -``` +
+

Portability

+

+{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. +

+

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

+

+
-## Safety +
+

Open source

+

+ {fmt} is in top hundred open-source 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 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.md#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. - - - GitHub Repository - +