source/misc/embedded_libs/fmt-11.0.2/doc/api.md

# API Reference The {fmt} library API consists of the following components: - [`fmt/base.h`](#base-api): the base API providing main formatting functions for `char`/UTF-8 with C++20 compile-time checks and minimal dependencies - [`fmt/format.h`](#format-api): `fmt::format` and other formatting functions as well as locale support - [`fmt/ranges.h`](#ranges-api): formatting of ranges and tuples - [`fmt/chrono.h`](#chrono-api): date and time formatting - [`fmt/std.h`](#std-api): formatters for standard library types - [`fmt/compile.h`](#compile-api): format string compilation - [`fmt/color.h`](#color-api): terminal colors and text styles - [`fmt/os.h`](#os-api): system APIs - [`fmt/ostream.h`](#ostream-api): `std::ostream` support - [`fmt/args.h`](#args-api): dynamic argument lists - [`fmt/printf.h`](#printf-api): safe `printf` - [`fmt/xchar.h`](#xchar-api): optional `wchar_t` support All functions and types provided by the library reside in namespace `fmt` and macros have prefix `FMT_`. ## Base API `fmt/base.h` defines the base API which provides main formatting functions for `char`/UTF-8 with C++20 compile-time checks. It has minimal include dependencies for better compile times. This header is only beneficial when using {fmt} as a library (the default) and not in the header-only mode. It also provides `formatter` specializations for the following types: - `int`, `long long`, - `unsigned`, `unsigned long long` - `float`, `double`, `long double` - `bool` - `char` - `const char*`, [`fmt::string_view`](#basic_string_view) - `const void*` The following functions use [format string syntax](syntax.md) similar to that of [str.format](https://docs.python.org/3/library/stdtypes.html#str.format) in Python. They take *fmt* and *args* as arguments. *fmt* is a format string that contains literal text and replacement fields surrounded by braces `{}`. The fields are replaced with formatted arguments in the resulting string. [`fmt::format_string`](#format_string) is a format string which can be implicitly constructed from a string literal or a `constexpr` string and is checked at compile time in C++20. To pass a runtime format string wrap it in [`fmt::runtime`](#runtime). *args* is an argument list representing objects to be formatted. I/O errors are reported as [`std::system_error`]( https://en.cppreference.com/w/cpp/error/system_error) exceptions unless specified otherwise. ::: print(format_string<T...>, T&&...) ::: print(FILE*, format_string<T...>, T&&...) ::: println(format_string<T...>, T&&...) ::: println(FILE*, format_string<T...>, T&&...) ::: format_to(OutputIt&&, format_string<T...>, T&&...) ::: format_to_n(OutputIt, size_t, format_string<T...>, T&&...) ::: format_to_n_result ::: formatted_size(format_string<T...>, T&&...) <a id="udt"></a> ### Formatting User-Defined Types The {fmt} library provides formatters for many standard C++ types. See [`fmt/ranges.h`](#ranges-api) for ranges and tuples including standard containers such as `std::vector`, [`fmt/chrono.h`](#chrono-api) for date and time formatting and [`fmt/std.h`](#std-api) for other standard library types. There are two ways to make a user-defined type formattable: providing a `format_as` function or specializing the `formatter` struct template. Use `format_as` if you want to make your type formattable as some other type with the same format specifiers. The `format_as` function should take an object of your type and return an object of a formattable type. It should be defined in the same namespace as your type. Example ([run](https://godbolt.org/z/nvME4arz8)): #include <fmt/format.h> namespace kevin_namespacy { enum class film { house_of_cards, american_beauty, se7en = 7 }; auto format_as(film f) { return fmt::underlying(f); } } int main() { fmt::print("{}\n", kevin_namespacy::film::se7en); // Output: 7 } Using specialization is more complex but gives you full control over parsing and formatting. To use this method specialize the `formatter` struct template for your type and implement `parse` and `format` methods. The recommended way of defining a formatter is by reusing an existing one via inheritance or composition. This way you can support standard format specifiers without implementing them yourself. For example: ```c++ // color.h: #include <fmt/base.h> enum class color {red, green, blue}; template <> struct fmt::formatter<color>: formatter<string_view> { // parse is inherited from formatter<string_view>. auto format(color c, format_context& ctx) const -> format_context::iterator; }; ``` ```c++ // color.cc: #include "color.h" #include <fmt/format.h> auto fmt::formatter<color>::format(color c, format_context& ctx) const -> format_context::iterator { string_view name = "unknown"; switch (c) { case color::red: name = "red"; break; case color::green: name = "green"; break; case color::blue: name = "blue"; break; } return formatter<string_view>::format(name, ctx); } ``` Note that `formatter<string_view>::format` is defined in `fmt/format.h` so it has to be included in the source file. Since `parse` is inherited from `formatter<string_view>` it will recognize all string format specifications, for example ```c++ fmt::format("{:>10}", color::blue) ``` will return `" blue"`. <!-- The experimental `nested_formatter` provides an easy way of applying a formatter to one or more subobjects. For example: #include <fmt/format.h> struct point { double x, y; }; template <> struct fmt::formatter<point> : nested_formatter<double> { auto format(point p, format_context& ctx) const { return write_padded(ctx, [=](auto out) { return format_to(out, "({}, {})", this->nested(p.x), this->nested(p.y)); }); } }; int main() { fmt::print("[{:>20.2f}]", point{1, 2}); } prints: [ (1.00, 2.00)] Notice that fill, align and width are applied to the whole object which is the recommended behavior while the remaining specifiers apply to elements. --> In general the formatter has the following form: template <> struct fmt::formatter<T> { // Parses format specifiers and stores them in the formatter. // // [ctx.begin(), ctx.end()) is a, possibly empty, character range that // contains a part of the format string starting from the format // specifications to be parsed, e.g. in // // fmt::format("{:f} continued", ...); // // the range will contain "f} continued". The formatter should parse // specifiers until '}' or the end of the range. In this example the // formatter should parse the 'f' specifier and return an iterator // pointing to '}'. constexpr auto parse(format_parse_context& ctx) -> format_parse_context::iterator; // Formats value using the parsed format specification stored in this // formatter and writes the output to ctx.out(). auto format(const T& value, format_context& ctx) const -> format_context::iterator; }; It is recommended to at least support fill, align and width that apply to the whole object and have the same semantics as in standard formatters. You can also write a formatter for a hierarchy of classes: ```c++ // demo.h: #include <type_traits> #include <fmt/core.h> struct A { virtual ~A() {} virtual std::string name() const { return "A"; } }; struct B : A { virtual std::string name() const { return "B"; } }; template <typename T> struct fmt::formatter<T, std::enable_if_t<std::is_base_of_v<A, T>, char>> : fmt::formatter<std::string> { auto format(const A& a, format_context& ctx) const { return formatter<std::string>::format(a.name(), ctx); } }; ``` ```c++ // demo.cc: #include "demo.h" #include <fmt/format.h> int main() { B b; A& a = b; fmt::print("{}", a); // Output: B } ``` Providing both a `formatter` specialization and a `format_as` overload is disallowed. ::: basic_format_parse_context ::: context ::: format_context ### Compile-Time Checks Compile-time format string checks are enabled by default on compilers that support C++20 `consteval`. On older compilers you can use the [FMT_STRING](#legacy-checks) macro defined in `fmt/format.h` instead. Unused arguments are allowed as in Python's `str.format` and ordinary functions. ::: basic_format_string ::: format_string ::: runtime(string_view) ### Named Arguments ::: arg(const Char*, const T&) Named arguments are not supported in compile-time checks at the moment. ### Type Erasure You can create your own formatting function with compile-time checks and small binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)): ```c++ #include <fmt/format.h> void vlog(const char* file, int line, fmt::string_view fmt, fmt::format_args args) { fmt::print("{}: {}: {}", file, line, fmt::vformat(fmt, args)); } template <typename... T> void log(const char* file, int line, fmt::format_string<T...> fmt, T&&... args) { vlog(file, line, fmt, fmt::make_format_args(args...)); } #define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__) MY_LOG("invalid squishiness: {}", 42); ``` Note that `vlog` is not parameterized on argument types which improves compile times and reduces binary code size compared to a fully parameterized version. ::: make_format_args(T&...) ::: basic_format_args ::: format_args ::: basic_format_arg ### Compatibility ::: basic_string_view ::: string_view ## Format API `fmt/format.h` defines the full format API providing additional formatting functions and locale support. <a id="format"></a> ::: format(format_string<T...>, T&&...) ::: vformat(string_view, format_args) ::: operator""_a() ### Utilities ::: ptr(T) ::: underlying(Enum) ::: to_string(const T&) ::: group_digits(T) ::: detail::buffer ::: basic_memory_buffer ### 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. ::: system_error ::: format_system_error ### Custom Allocators The {fmt} library supports custom dynamic memory allocators. A custom allocator class can be specified as a template argument to [`fmt::basic_memory_buffer`](#basic_memory_buffer): using custom_memory_buffer = fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>; It is also possible to write a formatting function that uses a custom allocator: using custom_string = std::basic_string<char, std::char_traits<char>, custom_allocator>; custom_string vformat(custom_allocator alloc, fmt::string_view format_str, fmt::format_args args) { auto buf = custom_memory_buffer(alloc); fmt::vformat_to(std::back_inserter(buf), format_str, args); return custom_string(buf.data(), buf.size(), alloc); } template <typename ...Args> inline custom_string format(custom_allocator alloc, fmt::string_view format_str, const Args& ... args) { return vformat(alloc, format_str, fmt::make_format_args(args...)); } The allocator will be used for the output container only. Formatting functions normally don't do any allocations for built-in and string types except for non-default floating-point formatting that occasionally falls back on `sprintf`. ### Locale All formatting is locale-independent by default. Use the `'L'` format specifier to insert the appropriate number separator characters from the locale: #include <fmt/core.h> #include <locale> std::locale::global(std::locale("en_US.UTF-8")); auto s = fmt::format("{:L}", 1000000); // s == "1,000,000" `fmt/format.h` provides the following overloads of formatting functions that take `std::locale` as a parameter. The locale type is a template parameter to avoid the expensive `<locale>` include. ::: format(const Locale&, format_string<T...>, T&&...) ::: format_to(OutputIt, const Locale&, format_string<T...>, T&&...) ::: formatted_size(const Locale&, format_string<T...>, T&&...) <a id="legacy-checks"></a> ### Legacy Compile-Time Checks `FMT_STRING` enables compile-time checks on older compilers. It requires C++14 or later and is a no-op in C++11. ::: FMT_STRING To force the use of legacy compile-time checks, define the preprocessor variable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting `FMT_STRING` will fail to compile with regular strings. <a id="ranges-api"></a> ## Range and Tuple Formatting `fmt/ranges.h` provides formatting support for ranges and tuples: #include <fmt/ranges.h> fmt::print("{}", std::tuple<char, int>{'a', 42}); // Output: ('a', 42) Using `fmt::join`, you can separate tuple elements with a custom separator: #include <fmt/ranges.h> auto t = std::tuple<int, char>{1, 'a'}; fmt::print("{}", fmt::join(t, ", ")); // Output: 1, a ::: join(Range&&, string_view) ::: join(It, Sentinel, string_view) ::: join(std::initializer_list<T>, string_view) <a id="chrono-api"></a> ## Date and Time Formatting `fmt/chrono.h` provides formatters for - [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration) - [`std::chrono::time_point`]( https://en.cppreference.com/w/cpp/chrono/time_point) - [`std::tm`](https://en.cppreference.com/w/cpp/chrono/c/tm) The format syntax is described in [Chrono Format Specifications](syntax.md# chrono-format-specifications). **Example**: #include <fmt/chrono.h> int main() { std::time_t t = std::time(nullptr); fmt::print("The date is {:%Y-%m-%d}.", fmt::localtime(t)); // Output: The date is 2020-11-07. // (with 2020-11-07 replaced by the current date) using namespace std::literals::chrono_literals; fmt::print("Default format: {} {}\n", 42s, 100ms); // Output: Default format: 42s 100ms fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s); // Output: strftime-like format: 03:15:30 } ::: localtime(std::time_t) ::: gmtime(std::time_t) <a id="std-api"></a> ## Standard Library Types Formatting `fmt/std.h` provides formatters for: - [`std::atomic`](https://en.cppreference.com/w/cpp/atomic/atomic) - [`std::atomic_flag`](https://en.cppreference.com/w/cpp/atomic/atomic_flag) - [`std::bitset`](https://en.cppreference.com/w/cpp/utility/bitset) - [`std::error_code`](https://en.cppreference.com/w/cpp/error/error_code) - [`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path) - [`std::monostate`](https://en.cppreference.com/w/cpp/utility/variant/monostate) - [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional) - [`std::source_location`](https://en.cppreference.com/w/cpp/utility/source_location) - [`std::thread::id`](https://en.cppreference.com/w/cpp/thread/thread/id) - [`std::variant`](https://en.cppreference.com/w/cpp/utility/variant/variant) ::: ptr(const std::unique_ptr<T, Deleter>&) ::: ptr(const std::shared_ptr<T>&) ### Formatting Variants A `std::variant` is only formattable if every variant alternative is formattable, and requires the `__cpp_lib_variant` [library feature](https://en.cppreference.com/w/cpp/feature_test). **Example**: #include <fmt/std.h> fmt::print("{}", std::variant<char, float>('x')); // Output: variant('x') fmt::print("{}", std::variant<std::monostate, char>()); // Output: variant(monostate) <a id="compile-api"></a> ## Format String Compilation `fmt/compile.h` provides format string compilation enabled via the `FMT_COMPILE` macro or the `_cf` user-defined literal defined in namespace `fmt::literals`. Format strings marked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into efficient formatting code at compile-time. This supports arguments of built-in and string types as well as user-defined types with `format` functions taking the format context type as a template parameter in their `formatter` specializations. For example: template <> struct fmt::formatter<point> { constexpr auto parse(format_parse_context& ctx); template <typename FormatContext> auto format(const point& p, FormatContext& ctx) const; }; Format string compilation can generate more binary code compared to the default API and is only recommended in places where formatting is a performance bottleneck. ::: FMT_COMPILE ::: operator""_cf <a id="color-api"></a> ## Terminal Colors and Text Styles `fmt/color.h` provides support for terminal color and text style output. ::: print(const text_style&, format_string<T...>, T&&...) ::: fg(detail::color_type) ::: bg(detail::color_type) ::: styled(const T&, text_style) <a id="os-api"></a> ## System APIs ::: ostream ::: windows_error <a id="ostream-api"></a> ## `std::ostream` Support `fmt/ostream.h` provides `std::ostream` support including formatting of user-defined types that have an overloaded insertion operator (`operator<<`). In order to make a type formattable via `std::ostream` you should provide a `formatter` specialization inherited from `ostream_formatter`: #include <fmt/ostream.h> struct date { int year, month, day; friend std::ostream& operator<<(std::ostream& os, const date& d) { return os << d.year << '-' << d.month << '-' << d.day; } }; template <> struct fmt::formatter<date> : ostream_formatter {}; std::string s = fmt::format("The date is {}", date{2012, 12, 9}); // s == "The date is 2012-12-9" ::: streamed(const T&) ::: print(std::ostream&, format_string<T...>, T&&...) <a id="args-api"></a> ## Dynamic Argument Lists The header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API that can be used to construct format argument lists dynamically. ::: dynamic_format_arg_store <a id="printf-api"></a> ## Safe `printf` The header `fmt/printf.h` provides `printf`-like formatting functionality. The following functions use [printf format string syntax](https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html) with the POSIX extension for positional arguments. Unlike their standard counterparts, the `fmt` functions are type-safe and throw an exception if an argument type doesn't match its format specification. ::: printf(string_view, const T&...) ::: fprintf(std::FILE*, const S&, const T&...) ::: sprintf(const S&, const T&...) <a id="xchar-api"></a> ## Wide Strings The optional header `fmt/xchar.h` provides support for `wchar_t` and exotic character types. ::: is_char ::: wstring_view ::: wformat_context ::: to_wstring(const T&) ## Compatibility with C++20 `std::format` {fmt} implements nearly all of the [C++20 formatting library](https://en.cppreference.com/w/cpp/utility/format) with the following differences: - Names are defined in the `fmt` namespace instead of `std` to avoid collisions with standard library implementations. - Width calculation doesn't use grapheme clusterization. The latter has been implemented in a separate branch but hasn't been integrated yet.