{"owner":"fmtlib","repo":"fmt","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":6493,"categories":["project-spec"],"hasMcp":false,"mcpConfig":null,"found":["doc/api.md"],"skills":{"doc/api.md":"# API Reference\n\nThe {fmt} library API consists of the following components:\n\n- [`fmt/core.h`](#core-api): the core API providing main formatting functions\n for `char`/UTF-8 with C++20 compile-time checks and minimal dependencies\n- [`fmt/format.h`](#format-api): `fmt::format` and other formatting functions\n as well as locale support\n- [`fmt/ranges.h`](#ranges-api): formatting of ranges and tuples\n- [`fmt/chrono.h`](#chrono-api): date and time formatting\n- [`fmt/std.h`](#std-api): formatters for standard library types\n- [`fmt/enum.h`](#enum-api): formatting of annotated enums\n- [`fmt/compile.h`](#compile-api): format string compilation\n- [`fmt/color.h`](#color-api): terminal colors and text styles\n- [`fmt/os.h`](#os-api): system APIs\n- [`fmt/ostream.h`](#ostream-api): `std::ostream` support\n- [`fmt/args.h`](#args-api): dynamic argument lists\n- [`fmt/printf.h`](#printf-api): safe `printf`\n- [`fmt/xchar.h`](#xchar-api): optional `wchar_t` support\n\nAll functions and types provided by the library reside in namespace `fmt`\nand macros have prefix `FMT_`.\n\n## C++ Module API\n\nWith the C++ module API, the headers listed above don't need to be included.\nYou can use the `import fmt;` statement instead. All other functionality,\nlisted below, remains the same.\n\n## Core API\n\n`fmt/core.h` defines the core API which provides main formatting functions\nfor `char`/UTF-8 with C++20 compile-time checks. It has minimal include\ndependencies for better compile times. This header is only beneficial when\nusing {fmt} as a library (the default) and not in the header-only mode.\nIt also provides `formatter` specializations for the following types:\n\n- `int`, `long long`\n- `unsigned`, `unsigned long long`\n- `float`, `double`, `long double`\n- `bool`\n- `char`\n- `const char*`, [`fmt::string_view`](#basic_string_view)\n- `const void*`\n\nThe following functions use [format string syntax](syntax.md) similar to that\nof [str.format](https://docs.python.org/3/library/stdtypes.html#str.format)\nin Python. They take *fmt* and *args* as arguments.\n\n*fmt* is a format string that contains literal text and replacement fields\nsurrounded by braces `{}`. The fields are replaced with formatted arguments\nin the resulting string. [`fmt::format_string`](#format_string) is a format\nstring which can be implicitly constructed from a string literal or a\n`constexpr` string and is checked at compile time in C++20. To pass a runtime\nformat string wrap it in [`fmt::runtime`](#runtime).\n\n*args* is an argument list representing objects to be formatted.\n\nI/O errors are reported as [`std::system_error`](\nhttps://en.cppreference.com/w/cpp/error/system_error) exceptions unless\nspecified otherwise.\n\n::: print(format_string, T&&...)\n\n::: print(FILE*, format_string, T&&...)\n\n::: println(format_string, T&&...)\n\n::: println(FILE*, format_string, T&&...)\n\n::: format_to(OutputIt&&, format_string, T&&...)\n\n::: format_to_n(OutputIt, size_t, format_string, T&&...)\n\n::: format_to_n_result\n\n::: formatted_size(format_string, T&&...)\n\n\n### Formatting User-Defined Types\n\nThe {fmt} library provides formatters for many standard C++ types.\nSee [`fmt/ranges.h`](#ranges-api) for ranges and tuples including standard\ncontainers such as `std::vector`, [`fmt/chrono.h`](#chrono-api) for date and\ntime formatting and [`fmt/std.h`](#std-api) for other standard library types.\n\nThere are two ways to make a user-defined type formattable: providing a\n`format_as` function or specializing the `formatter` struct template.\nFormatting of non-void pointer types is intentionally disallowed and they\ncannot be made formattable via either extension API.\n\nUse `format_as` if you want to make your type formattable as some other\ntype with the same format specifiers. The `format_as` function should\ntake an object of your type and return an object of a formattable type.\nIt should be defined in the same namespace as your type.\n`format_as` cannot be used when a type also matches another `formatter`\nspecialization, such as the range `formatter`, because the specializations\nwould be ambiguous. Disable the conflicting specialization, if possible,\nor provide an explicit `formatter` specialization instead.\n\nExample ([run](https://godbolt.org/z/nvME4arz8)):\n\n #include \n\n namespace kevin_namespacy {\n\n enum class film {\n house_of_cards, american_beauty, se7en = 7\n };\n\n auto format_as(film f) { return fmt::underlying(f); }\n\n }\n\n int main() {\n fmt::print(\"{}\\n\", kevin_namespacy::film::se7en); // Output: 7\n }\n\nUsing a specialization is more complex, but gives you full control over\nparsing and formatting. To use this method, specialize the `formatter`\nstruct template for your type and implement `parse` and `format`\nmethods.\n\nThe recommended way of defining a formatter is by reusing an existing\none via inheritance or composition. This way you can support standard\nformat specifiers without implementing them yourself. For example:\n\n```c++\n// color.h:\n#include \n\nenum class color {red, green, blue};\n\ntemplate <> struct fmt::formatter: formatter {\n // parse is inherited from formatter.\n\n auto format(color c, format_context& ctx) const\n -> format_context::iterator;\n};\n```\n\n```c++\n// color.cc:\n#include \"color.h\"\n#include \n\nauto fmt::formatter::format(color c, format_context& ctx) const\n -> format_context::iterator {\n string_view name = \"unknown\";\n switch (c) {\n case color::red: name = \"red\"; break;\n case color::green: name = \"green\"; break;\n case color::blue: name = \"blue\"; break;\n }\n return formatter::format(name, ctx);\n}\n```\n\nNote that `formatter::format` is defined in `fmt/format.h`\nso it has to be included in the source file. Since `parse` is inherited\nfrom `formatter` it will recognize all string format\nspecifications, for example\n\n```c++\nfmt::format(\"{:>10}\", color::blue)\n```\n\nwill return `\" blue\"`.\n\n\n\nIn general the formatter has the following form:\n\n template <> struct fmt::formatter {\n // Parses format specifiers and stores them in the formatter.\n //\n // [ctx.begin(), ctx.end()) is a, possibly empty, character range that\n // contains a part of the format string starting from the format\n // specifications to be parsed, e.g. in\n //\n // fmt::format(\"{:f} continued\", ...);\n //\n // the range will contain \"f} continued\". The formatter should parse\n // specifiers until '}' or the end of the range. In this example the\n // formatter should parse the 'f' specifier and return an iterator\n // pointing to '}'.\n constexpr auto parse(format_parse_context& ctx)\n -> format_parse_context::iterator;\n\n // Formats value using the parsed format specification stored in this\n // formatter and writes the output to ctx.out().\n auto format(const T& value, format_context& ctx) const\n -> format_context::iterator;\n };\n\nIt is recommended to at least support fill, align and width that apply\nto the whole object and have the same semantics as in standard\nformatters.\n\nYou can also write a formatter for a hierarchy of classes:\n\n```c++\n// demo.h:\n#include \n#include \n\nstruct A {\n virtual ~A() {}\n virtual std::string name() const { return \"A\"; }\n};\n\nstruct B : A {\n virtual std::string name() const { return \"B\"; }\n};\n\ntemplate \nstruct fmt::formatter, char>> :\n fmt::formatter {\n auto format(const A& a, format_context& ctx) const {\n return formatter::format(a.name(), ctx);\n }\n};\n```\n\n```c++\n// demo.cc:\n#include \"demo.h\"\n#include \n\nint main() {\n B b;\n A& a = b;\n fmt::print(\"{}\", a); // Output: B\n}\n```\n\nProviding both a `formatter` specialization and a `format_as` overload is\ndisallowed.\n\n::: basic_format_parse_context\n\n::: context\n\n::: format_context\n\n### Compile-Time Checks\n\nCompile-time format string checks are enabled by default on compilers\nthat support C++20 `consteval`. On older compilers you can use the\n[FMT_STRING](#legacy-checks) macro defined in `fmt/format.h` instead.\n\nUnused arguments are allowed as in Python's `str.format` and ordinary functions.\n\nSee [Type Erasure](#type-erasure) for an example of how to enable compile-time\nchecks in your own functions with `fmt::format_string` while avoiding template\nbloat.\n\n::: fstring\n\n::: format_string\n\n::: runtime(string_view)\n\n### Type Erasure\n\nYou can create your own formatting function with compile-time checks and\nsmall binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):\n\n```c++\n#include \n\nvoid vlog(const char* file, int line,\n fmt::string_view fmt, fmt::format_args args) {\n fmt::print(\"{}: {}: {}\", file, line, fmt::vformat(fmt, args));\n}\n\ntemplate \nvoid log(const char* file, int line,\n fmt::format_string fmt, T&&... args) {\n vlog(file, line, fmt, fmt::make_format_args(args...));\n}\n\n#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)\n\nMY_LOG(\"invalid squishiness: {}\", 42);\n```\n\nNote that `vlog` is not parameterized on argument types which improves\ncompile times and reduces binary code size compared to a fully\nparameterized version.\n\n::: make_format_args(T&...)\n\n::: basic_format_args\n\n::: format_args\n\n::: basic_format_arg\n\n### Named Arguments\n\n::: arg(const char*, const T&)\n\n### Compatibility\n\n::: basic_string_view\n\n::: string_view\n\n## Format API\n\n`fmt/format.h` defines the full format API providing additional\nformatting functions and locale support.\n\n\n::: format(format_string, T&&...)\n\n::: vformat(string_view, format_args)\n\n::: operator\"\"_a()\n\n### Utilities\n\n::: ptr(T)\n\n::: underlying(Enum)\n\n::: to_string(const T&)\n\n::: group_digits(T)\n\n::: detail::buffer\n\n::: basic_memory_buffer\n\n### System Errors\n\n{fmt} does not use `errno` to communicate errors to the user, but it may\ncall system functions which set `errno`. Users should not make any\nassumptions about the value of `errno` being preserved by library\nfunctions.\n\n::: system_error\n\n::: format_system_error\n\n### Custom Allocators\n\nThe {fmt} library supports custom dynamic memory allocators. A custom\nallocator class can be specified as a template argument to\n[`fmt::basic_memory_buffer`](#basic_memory_buffer):\n\n using custom_memory_buffer = \n fmt::basic_memory_buffer;\n\nIt is also possible to write a formatting function that uses a custom\nallocator:\n\n using custom_string =\n std::basic_string, custom_allocator>;\n\n auto vformat(custom_allocator alloc, fmt::string_view fmt,\n fmt::format_args args) -> custom_string {\n auto buf = custom_memory_buffer(alloc);\n fmt::vformat_to(std::back_inserter(buf), fmt, args);\n return custom_string(buf.data(), buf.size(), alloc);\n }\n\n template \n auto format(custom_allocator alloc, fmt::string_view fmt,\n const Args& ... args) -> custom_string {\n return vformat(alloc, fmt, fmt::make_format_args(args...));\n }\n\nThe allocator will be used for the output container only. Formatting\nfunctions normally don't do any allocations for built-in and string\ntypes except for non-default floating-point formatting that occasionally\nfalls back on `sprintf`.\n\n### Locale\n\nAll formatting is locale-independent by default. Use the `'L'` format\nspecifier to insert the appropriate number separator characters from the\nlocale:\n\n #include \n #include \n\n std::locale::global(std::locale(\"en_US.UTF-8\"));\n auto s = fmt::format(\"{:L}\", 1000000); // s == \"1,000,000\"\n\n`fmt/format.h` provides the following overloads of formatting functions\nthat take `std::locale` as a parameter. The locale type is a template\nparameter to avoid the expensive `` include.\n\n::: format(locale_ref, format_string, T&&...)\n\n::: format_to(OutputIt, locale_ref, format_string, T&&...)\n\n::: formatted_size(locale_ref, format_string, T&&...)\n\n\n### Legacy Compile-Time Checks\n\n`FMT_STRING` enables compile-time checks on older compilers. It requires\nC++14 or later and is a no-op in C++11.\n\n::: FMT_STRING\n\nTo force the use of legacy compile-time checks, define the preprocessor\nvariable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting\n`FMT_STRING` will fail to compile with regular strings.\n\n\n## Range and Tuple Formatting\n\n`fmt/ranges.h` provides formatting support for ranges and tuples:\n\n #include \n\n fmt::print(\"{}\", std::tuple{'a', 42});\n // Output: ('a', 42)\n\nUsing `fmt::join`, you can separate tuple elements with a custom separator:\n\n #include \n\n auto t = std::tuple{1, 'a'};\n fmt::print(\"{}\", fmt::join(t, \", \"));\n // Output: 1, a\n\n::: join(Range&&, string_view)\n\n::: join(It, Sentinel, string_view)\n\n::: join(std::initializer_list, string_view)\n\n\n## Date and Time Formatting\n\n`fmt/chrono.h` provides formatters for\n\n- [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)\n- [`std::chrono::time_point`](\n https://en.cppreference.com/w/cpp/chrono/time_point)\n- [`std::tm`](https://en.cppreference.com/w/cpp/chrono/c/tm)\n\nThe format syntax is described in [Chrono Format Specifications](syntax.md#\nchrono-format-spec).\n\n**Example**:\n\n #include \n\n int main() {\n auto now = std::chrono::system_clock::now();\n\n fmt::print(\"The date is {:%Y-%m-%d}.\\n\", now);\n // Output: The date is 2020-11-07.\n // (with 2020-11-07 replaced by the current date)\n\n using namespace std::literals::chrono_literals;\n\n fmt::print(\"Default format: {} {}\\n\", 42s, 100ms);\n // Output: Default format: 42s 100ms\n\n fmt::print(\"strftime-like format: {:%H:%M:%S}\\n\", 3h + 15min + 30s);\n // Output: strftime-like format: 03:15:30\n }\n\n::: gmtime(std::time_t)\n\n\n## Standard Library Types Formatting\n\n`fmt/std.h` provides formatters for:\n\n- [`std::atomic`](https://en.cppreference.com/w/cpp/atomic/atomic)\n- [`std::atomic_flag`](https://en.cppreference.com/w/cpp/atomic/atomic_flag)\n- [`std::bitset`](https://en.cppreference.com/w/cpp/utility/bitset)\n- [`std::error_code`](https://en.cppreference.com/w/cpp/error/error_code)\n- [`std::exception`](https://en.cppreference.com/w/cpp/error/exception)\n- [`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path)\n- [`std::monostate`](\n https://en.cppreference.com/w/cpp/utility/variant/monostate)\n- [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional)\n- [`std::source_location`](\n https://en.cppreference.com/w/cpp/utility/source_location)\n- [`std::thread::id`](https://en.cppreference.com/w/cpp/thread/thread/id)\n- [`std::variant`](https://en.cppreference.com/w/cpp/utility/variant/variant)\n\n::: ptr(const std::unique_ptr&)\n\n::: ptr(const std::shared_ptr&)\n\n### Variants\n\nA `std::variant` can be formatted only if every alternative is\nformattable, and requires the `__cpp_lib_variant` [library\nfeature](https://en.cppreference.com/w/cpp/feature_test).\n\n**Example**:\n\n #include \n\n fmt::print(\"{}\", std::variant('x'));\n // Output: variant('x')\n\n fmt::print(\"{}\", std::variant());\n // Output: variant(monostate)\n\n## Bit-Fields and Packed Structs\n\nTo format a bit-field or a field of a struct with `__attribute__((packed))`\napplied to it, you need to convert it to the underlying or compatible type via\na cast or a unary `+` ([godbolt](https://www.godbolt.org/z/3qKKs6T5Y)):\n\n```c++\nstruct smol {\n int bit : 1;\n};\n\nauto s = smol();\nfmt::print(\"{}\", +s.bit);\n```\n\nThis is a known limitation of \"perfect\" forwarding in C++.\n\n\n## Enum Formatting\n\n`fmt/enum.h` provides formatting of enums annotated with\n`fmt::as_identifiers`. Such an enum is formatted as the identifier of the\nenumerator matching the formatted value:\n\n #include \n\n enum class [[=fmt::as_identifiers]] color { red, green, blue };\n\n fmt::print(\"{}\", color::green);\n // Output: green\n\nSuch enums are formatted using the string [Format Specification](\nsyntax.md#format-specification), for example:\n\n fmt::print(\"[{:>7}]\", color::red);\n // Output: [ red]\n\nIdentifiers are only available as `char` strings so annotated enums are not\nformattable with other character types.\n\nIf several enumerators have the same value, the first one in the order of\ndeclaration is used. A value that doesn't match any enumerator is represented\nas its underlying value in decimal before applying string formatting:\n\n fmt::print(\"{}\", static_cast(42));\n // Output: 42\n\nAn enum annotated with `fmt::as_underlying` is instead formatted as its\nunderlying value using the integer [Format Specification](\nsyntax.md#format-specification):\n\n enum class [[=fmt::as_underlying]] color { red = 1, green = 2, blue = 4 };\n\n fmt::print(\"{:04x}\", color::blue);\n // Output: 0004\n\nSuch an enum is mapped to its underlying type before type erasure, so it can\nalso be used as dynamic width or precision. Unlike `fmt::as_identifiers`, it\nworks with all character types. The two annotations specify different\nrepresentations and cannot be combined.\n\nEnums without an annotation are not affected and are formatted as before, i.e.\nscoped enums require `format_as` or a `formatter` specialization, see\n[Formatting User-Defined Types](#udt).\n\nThis uses two C++26 features:\n[reflection](https://en.cppreference.com/w/cpp/language/operator_reflection) to\nretrieve the enumerator identifiers and\n[annotations](https://en.cppreference.com/w/cpp/language/annotations) to opt an\nenum in via `fmt::as_identifiers`. It therefore requires a compiler with\nreflection support,\nwhich may need an extra flag such as `-freflection` in GCC. The macro\n`FMT_USE_REFLECTION` is set to 1 if reflection is available and to 0 otherwise.\nIt can also be defined by the user to disable the use of reflection.\n\nWhen {fmt} is built as a module, reflection support is detected when the module\nitself is compiled, so this API is only available to importers if the module was\nbuilt with reflection enabled.\n\n\n## Compile-Time Support\n\n`fmt/compile.h` provides format string compilation and compile-time\n(`constexpr`) formatting enabled via the `FMT_COMPILE` macro or the `_cf`\nuser-defined literal defined in namespace `fmt::literals`. Format strings\nmarked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into\nefficient formatting code at compile-time. This supports arguments of built-in\nand string types as well as user-defined types with `format` methods taking\nthe format context type as a template parameter in their `formatter`\nspecializations. For example ([run](https://www.godbolt.org/z/3c13erEoq)):\n\n struct point {\n double x;\n double y;\n };\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n using namespace fmt::literals;\n std::string s = fmt::format(\"{}\"_cf, point(4, 2));\n\nFormat string compilation can generate more binary code compared to the\ndefault API and is only recommended in places where formatting is a\nperformance bottleneck.\n\nThe same APIs support formatting at compile time e.g. in `constexpr`\nand `consteval` functions. Additionally there is an experimental\n`FMT_STATIC_FORMAT` that allows formatting into a string of the exact\nrequired size at compile time. Compile-time formatting works with built-in\nand user-defined formatters that have `constexpr` `format` methods.\nExample:\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n constexpr auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n constexpr auto s = FMT_STATIC_FORMAT(\"{}\", point(4, 2));\n const char* cstr = s.c_str(); // Points the static string \"(4, 2)\".\n\n::: operator\"\"_cf\n\n::: FMT_COMPILE\n\n::: FMT_STATIC_FORMAT\n\n\n## Terminal Colors and Text Styles\n\n`fmt/color.h` provides support for terminal color and text style output.\n\n::: print(text_style, format_string, T&&...)\n\n::: fg(detail::color_type)\n\n::: bg(detail::color_type)\n\n::: styled(const T&, text_style)\n\n\n## System APIs\n\n::: ostream\n\n::: output_file(cstring_view, T...)\n\n::: windows_error\n\n\n## `std::ostream` Support\n\n`fmt/ostream.h` provides `std::ostream` support including formatting of\nuser-defined types that have an overloaded insertion operator\n(`operator<<`). In order to make a type formattable via `std::ostream`\nyou should provide a `formatter` specialization inherited from\n`ostream_formatter`:\n\n #include \n\n struct date {\n int year, month, day;\n\n friend std::ostream& operator<<(std::ostream& os, const date& d) {\n return os << d.year << '-' << d.month << '-' << d.day;\n }\n };\n\n template <> struct fmt::formatter : ostream_formatter {};\n\n std::string s = fmt::format(\"The date is {}\", date{2012, 12, 9});\n // s == \"The date is 2012-12-9\"\n\n::: streamed(const T&)\n\n::: print(std::ostream&, format_string, T&&...)\n\n\n## Dynamic Argument Lists\n\nThe header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API\nthat can be used to construct format argument lists dynamically.\n\n::: dynamic_format_arg_store\n\n\n## Safe `printf`\n\nThe header `fmt/printf.h` provides `printf`-like formatting\nfunctionality. The following functions use [printf format string\nsyntax](https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html)\nwith the POSIX extension for positional arguments. Unlike their standard\ncounterparts, the `fmt` functions are type-safe and throw an exception\nif an argument type doesn't match its format specification.\n\n::: printf(string_view, const T&...)\n\n::: fprintf(std::FILE*, string_view, const T&...)\n\n::: sprintf(string_view, const T&...)\n\n\n## Wide Strings\n\nThe optional header `fmt/xchar.h` provides support for `wchar_t` and\nexotic character types.\n\n::: wstring_view\n\n::: wformat_context\n\n::: to_wstring(const T&)\n\n## Compatibility with C++20 `std::format`\n\n{fmt} implements nearly all of the [C++20 formatting\nlibrary](https://en.cppreference.com/w/cpp/utility/format) with the\nfollowing differences:\n\n- Names are defined in the `fmt` namespace instead of `std` to avoid\n collisions with standard library implementations.\n\n- Width calculation doesn't use grapheme clusterization. The latter has\n been implemented in a separate branch but hasn't been integrated yet.\n\n- The default floating-point representation in {fmt} uses the smallest\n precision that provides round-trip guarantees similarly to other languages\n like Java and Python. `std::format` is currently specified in terms of\n `std::to_chars` which tries to generate the smallest number of characters\n (ignoring redundant digits and sign in exponent) and may produce more\n decimal digits than necessary.\n\n## Configuration Options\n\n{fmt} provides configuration via CMake options and preprocessor macros to\nenable or disable features and to optimize for binary size. For example, you\ncan disable OS-specific APIs defined in `fmt/os.h` with `-DFMT_OS=OFF` when\nconfiguring CMake.\n\n### CMake Options\n\n- **`FMT_OS`**: When set to `OFF`, disables OS-specific APIs (`fmt/os.h`).\n- **`FMT_UNICODE`**: When set to `OFF`, disables Unicode support on\n Windows/MSVC. Unicode support is always enabled on other platforms.\n\n### Macros\n\n- **`FMT_HEADER_ONLY`**: Enables the header-only mode when defined. It is an\n alternative to using the `fmt::fmt-header-only` CMake target.\n Default: not defined.\n\n- **`FMT_USE_EXCEPTIONS`**: Disables the use of exceptions when set to `0`.\n Default: `1` (`0` if compiled with `-fno-exceptions`).\n\n- **`FMT_USE_LOCALE`**: When set to `0`, disables locale support.\n Default: `1` (`0` when `FMT_OPTIMIZE_SIZE > 1`).\n\n- **`FMT_CUSTOM_ASSERT_FAIL`**: When set to `1`, allows users to provide a\n custom `fmt::assert_fail` function which is called on assertion failures and,\n if exceptions are disabled, on runtime errors. Default: `0`.\n\n- **`FMT_BUILTIN_TYPES`**: When set to `0`, disables built-in handling of\n arithmetic and string types other than `int`. This reduces library size at\n the cost of per-call overhead. Default: `1`.\n\n- **`FMT_OPTIMIZE_SIZE`**: Controls binary size optimizations:\n - `0` - off (default)\n - `1` - applies some optimizations\n - `2` - disables locale support by default, some Unicode features, and\n named arguments, and applies more aggressive optimizations\n\n### Binary Size Optimization\n\nTo minimize the binary footprint of {fmt} as much as possible at the cost of\nsome features, you can use the following configuration:\n\n- CMake options:\n - `FMT_OS=OFF`\n- Macros:\n - `FMT_BUILTIN_TYPES=0`\n - `FMT_OPTIMIZE_SIZE=2`\n"},"files":{"doc/api.md":"# API Reference\n\nThe {fmt} library API consists of the following components:\n\n- [`fmt/core.h`](#core-api): the core API providing main formatting functions\n for `char`/UTF-8 with C++20 compile-time checks and minimal dependencies\n- [`fmt/format.h`](#format-api): `fmt::format` and other formatting functions\n as well as locale support\n- [`fmt/ranges.h`](#ranges-api): formatting of ranges and tuples\n- [`fmt/chrono.h`](#chrono-api): date and time formatting\n- [`fmt/std.h`](#std-api): formatters for standard library types\n- [`fmt/enum.h`](#enum-api): formatting of annotated enums\n- [`fmt/compile.h`](#compile-api): format string compilation\n- [`fmt/color.h`](#color-api): terminal colors and text styles\n- [`fmt/os.h`](#os-api): system APIs\n- [`fmt/ostream.h`](#ostream-api): `std::ostream` support\n- [`fmt/args.h`](#args-api): dynamic argument lists\n- [`fmt/printf.h`](#printf-api): safe `printf`\n- [`fmt/xchar.h`](#xchar-api): optional `wchar_t` support\n\nAll functions and types provided by the library reside in namespace `fmt`\nand macros have prefix `FMT_`.\n\n## C++ Module API\n\nWith the C++ module API, the headers listed above don't need to be included.\nYou can use the `import fmt;` statement instead. All other functionality,\nlisted below, remains the same.\n\n## Core API\n\n`fmt/core.h` defines the core API which provides main formatting functions\nfor `char`/UTF-8 with C++20 compile-time checks. It has minimal include\ndependencies for better compile times. This header is only beneficial when\nusing {fmt} as a library (the default) and not in the header-only mode.\nIt also provides `formatter` specializations for the following types:\n\n- `int`, `long long`\n- `unsigned`, `unsigned long long`\n- `float`, `double`, `long double`\n- `bool`\n- `char`\n- `const char*`, [`fmt::string_view`](#basic_string_view)\n- `const void*`\n\nThe following functions use [format string syntax](syntax.md) similar to that\nof [str.format](https://docs.python.org/3/library/stdtypes.html#str.format)\nin Python. They take *fmt* and *args* as arguments.\n\n*fmt* is a format string that contains literal text and replacement fields\nsurrounded by braces `{}`. The fields are replaced with formatted arguments\nin the resulting string. [`fmt::format_string`](#format_string) is a format\nstring which can be implicitly constructed from a string literal or a\n`constexpr` string and is checked at compile time in C++20. To pass a runtime\nformat string wrap it in [`fmt::runtime`](#runtime).\n\n*args* is an argument list representing objects to be formatted.\n\nI/O errors are reported as [`std::system_error`](\nhttps://en.cppreference.com/w/cpp/error/system_error) exceptions unless\nspecified otherwise.\n\n::: print(format_string, T&&...)\n\n::: print(FILE*, format_string, T&&...)\n\n::: println(format_string, T&&...)\n\n::: println(FILE*, format_string, T&&...)\n\n::: format_to(OutputIt&&, format_string, T&&...)\n\n::: format_to_n(OutputIt, size_t, format_string, T&&...)\n\n::: format_to_n_result\n\n::: formatted_size(format_string, T&&...)\n\n\n### Formatting User-Defined Types\n\nThe {fmt} library provides formatters for many standard C++ types.\nSee [`fmt/ranges.h`](#ranges-api) for ranges and tuples including standard\ncontainers such as `std::vector`, [`fmt/chrono.h`](#chrono-api) for date and\ntime formatting and [`fmt/std.h`](#std-api) for other standard library types.\n\nThere are two ways to make a user-defined type formattable: providing a\n`format_as` function or specializing the `formatter` struct template.\nFormatting of non-void pointer types is intentionally disallowed and they\ncannot be made formattable via either extension API.\n\nUse `format_as` if you want to make your type formattable as some other\ntype with the same format specifiers. The `format_as` function should\ntake an object of your type and return an object of a formattable type.\nIt should be defined in the same namespace as your type.\n`format_as` cannot be used when a type also matches another `formatter`\nspecialization, such as the range `formatter`, because the specializations\nwould be ambiguous. Disable the conflicting specialization, if possible,\nor provide an explicit `formatter` specialization instead.\n\nExample ([run](https://godbolt.org/z/nvME4arz8)):\n\n #include \n\n namespace kevin_namespacy {\n\n enum class film {\n house_of_cards, american_beauty, se7en = 7\n };\n\n auto format_as(film f) { return fmt::underlying(f); }\n\n }\n\n int main() {\n fmt::print(\"{}\\n\", kevin_namespacy::film::se7en); // Output: 7\n }\n\nUsing a specialization is more complex, but gives you full control over\nparsing and formatting. To use this method, specialize the `formatter`\nstruct template for your type and implement `parse` and `format`\nmethods.\n\nThe recommended way of defining a formatter is by reusing an existing\none via inheritance or composition. This way you can support standard\nformat specifiers without implementing them yourself. For example:\n\n```c++\n// color.h:\n#include \n\nenum class color {red, green, blue};\n\ntemplate <> struct fmt::formatter: formatter {\n // parse is inherited from formatter.\n\n auto format(color c, format_context& ctx) const\n -> format_context::iterator;\n};\n```\n\n```c++\n// color.cc:\n#include \"color.h\"\n#include \n\nauto fmt::formatter::format(color c, format_context& ctx) const\n -> format_context::iterator {\n string_view name = \"unknown\";\n switch (c) {\n case color::red: name = \"red\"; break;\n case color::green: name = \"green\"; break;\n case color::blue: name = \"blue\"; break;\n }\n return formatter::format(name, ctx);\n}\n```\n\nNote that `formatter::format` is defined in `fmt/format.h`\nso it has to be included in the source file. Since `parse` is inherited\nfrom `formatter` it will recognize all string format\nspecifications, for example\n\n```c++\nfmt::format(\"{:>10}\", color::blue)\n```\n\nwill return `\" blue\"`.\n\n\n\nIn general the formatter has the following form:\n\n template <> struct fmt::formatter {\n // Parses format specifiers and stores them in the formatter.\n //\n // [ctx.begin(), ctx.end()) is a, possibly empty, character range that\n // contains a part of the format string starting from the format\n // specifications to be parsed, e.g. in\n //\n // fmt::format(\"{:f} continued\", ...);\n //\n // the range will contain \"f} continued\". The formatter should parse\n // specifiers until '}' or the end of the range. In this example the\n // formatter should parse the 'f' specifier and return an iterator\n // pointing to '}'.\n constexpr auto parse(format_parse_context& ctx)\n -> format_parse_context::iterator;\n\n // Formats value using the parsed format specification stored in this\n // formatter and writes the output to ctx.out().\n auto format(const T& value, format_context& ctx) const\n -> format_context::iterator;\n };\n\nIt is recommended to at least support fill, align and width that apply\nto the whole object and have the same semantics as in standard\nformatters.\n\nYou can also write a formatter for a hierarchy of classes:\n\n```c++\n// demo.h:\n#include \n#include \n\nstruct A {\n virtual ~A() {}\n virtual std::string name() const { return \"A\"; }\n};\n\nstruct B : A {\n virtual std::string name() const { return \"B\"; }\n};\n\ntemplate \nstruct fmt::formatter, char>> :\n fmt::formatter {\n auto format(const A& a, format_context& ctx) const {\n return formatter::format(a.name(), ctx);\n }\n};\n```\n\n```c++\n// demo.cc:\n#include \"demo.h\"\n#include \n\nint main() {\n B b;\n A& a = b;\n fmt::print(\"{}\", a); // Output: B\n}\n```\n\nProviding both a `formatter` specialization and a `format_as` overload is\ndisallowed.\n\n::: basic_format_parse_context\n\n::: context\n\n::: format_context\n\n### Compile-Time Checks\n\nCompile-time format string checks are enabled by default on compilers\nthat support C++20 `consteval`. On older compilers you can use the\n[FMT_STRING](#legacy-checks) macro defined in `fmt/format.h` instead.\n\nUnused arguments are allowed as in Python's `str.format` and ordinary functions.\n\nSee [Type Erasure](#type-erasure) for an example of how to enable compile-time\nchecks in your own functions with `fmt::format_string` while avoiding template\nbloat.\n\n::: fstring\n\n::: format_string\n\n::: runtime(string_view)\n\n### Type Erasure\n\nYou can create your own formatting function with compile-time checks and\nsmall binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):\n\n```c++\n#include \n\nvoid vlog(const char* file, int line,\n fmt::string_view fmt, fmt::format_args args) {\n fmt::print(\"{}: {}: {}\", file, line, fmt::vformat(fmt, args));\n}\n\ntemplate \nvoid log(const char* file, int line,\n fmt::format_string fmt, T&&... args) {\n vlog(file, line, fmt, fmt::make_format_args(args...));\n}\n\n#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)\n\nMY_LOG(\"invalid squishiness: {}\", 42);\n```\n\nNote that `vlog` is not parameterized on argument types which improves\ncompile times and reduces binary code size compared to a fully\nparameterized version.\n\n::: make_format_args(T&...)\n\n::: basic_format_args\n\n::: format_args\n\n::: basic_format_arg\n\n### Named Arguments\n\n::: arg(const char*, const T&)\n\n### Compatibility\n\n::: basic_string_view\n\n::: string_view\n\n## Format API\n\n`fmt/format.h` defines the full format API providing additional\nformatting functions and locale support.\n\n\n::: format(format_string, T&&...)\n\n::: vformat(string_view, format_args)\n\n::: operator\"\"_a()\n\n### Utilities\n\n::: ptr(T)\n\n::: underlying(Enum)\n\n::: to_string(const T&)\n\n::: group_digits(T)\n\n::: detail::buffer\n\n::: basic_memory_buffer\n\n### System Errors\n\n{fmt} does not use `errno` to communicate errors to the user, but it may\ncall system functions which set `errno`. Users should not make any\nassumptions about the value of `errno` being preserved by library\nfunctions.\n\n::: system_error\n\n::: format_system_error\n\n### Custom Allocators\n\nThe {fmt} library supports custom dynamic memory allocators. A custom\nallocator class can be specified as a template argument to\n[`fmt::basic_memory_buffer`](#basic_memory_buffer):\n\n using custom_memory_buffer = \n fmt::basic_memory_buffer;\n\nIt is also possible to write a formatting function that uses a custom\nallocator:\n\n using custom_string =\n std::basic_string, custom_allocator>;\n\n auto vformat(custom_allocator alloc, fmt::string_view fmt,\n fmt::format_args args) -> custom_string {\n auto buf = custom_memory_buffer(alloc);\n fmt::vformat_to(std::back_inserter(buf), fmt, args);\n return custom_string(buf.data(), buf.size(), alloc);\n }\n\n template \n auto format(custom_allocator alloc, fmt::string_view fmt,\n const Args& ... args) -> custom_string {\n return vformat(alloc, fmt, fmt::make_format_args(args...));\n }\n\nThe allocator will be used for the output container only. Formatting\nfunctions normally don't do any allocations for built-in and string\ntypes except for non-default floating-point formatting that occasionally\nfalls back on `sprintf`.\n\n### Locale\n\nAll formatting is locale-independent by default. Use the `'L'` format\nspecifier to insert the appropriate number separator characters from the\nlocale:\n\n #include \n #include \n\n std::locale::global(std::locale(\"en_US.UTF-8\"));\n auto s = fmt::format(\"{:L}\", 1000000); // s == \"1,000,000\"\n\n`fmt/format.h` provides the following overloads of formatting functions\nthat take `std::locale` as a parameter. The locale type is a template\nparameter to avoid the expensive `` include.\n\n::: format(locale_ref, format_string, T&&...)\n\n::: format_to(OutputIt, locale_ref, format_string, T&&...)\n\n::: formatted_size(locale_ref, format_string, T&&...)\n\n\n### Legacy Compile-Time Checks\n\n`FMT_STRING` enables compile-time checks on older compilers. It requires\nC++14 or later and is a no-op in C++11.\n\n::: FMT_STRING\n\nTo force the use of legacy compile-time checks, define the preprocessor\nvariable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting\n`FMT_STRING` will fail to compile with regular strings.\n\n\n## Range and Tuple Formatting\n\n`fmt/ranges.h` provides formatting support for ranges and tuples:\n\n #include \n\n fmt::print(\"{}\", std::tuple{'a', 42});\n // Output: ('a', 42)\n\nUsing `fmt::join`, you can separate tuple elements with a custom separator:\n\n #include \n\n auto t = std::tuple{1, 'a'};\n fmt::print(\"{}\", fmt::join(t, \", \"));\n // Output: 1, a\n\n::: join(Range&&, string_view)\n\n::: join(It, Sentinel, string_view)\n\n::: join(std::initializer_list, string_view)\n\n\n## Date and Time Formatting\n\n`fmt/chrono.h` provides formatters for\n\n- [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)\n- [`std::chrono::time_point`](\n https://en.cppreference.com/w/cpp/chrono/time_point)\n- [`std::tm`](https://en.cppreference.com/w/cpp/chrono/c/tm)\n\nThe format syntax is described in [Chrono Format Specifications](syntax.md#\nchrono-format-spec).\n\n**Example**:\n\n #include \n\n int main() {\n auto now = std::chrono::system_clock::now();\n\n fmt::print(\"The date is {:%Y-%m-%d}.\\n\", now);\n // Output: The date is 2020-11-07.\n // (with 2020-11-07 replaced by the current date)\n\n using namespace std::literals::chrono_literals;\n\n fmt::print(\"Default format: {} {}\\n\", 42s, 100ms);\n // Output: Default format: 42s 100ms\n\n fmt::print(\"strftime-like format: {:%H:%M:%S}\\n\", 3h + 15min + 30s);\n // Output: strftime-like format: 03:15:30\n }\n\n::: gmtime(std::time_t)\n\n\n## Standard Library Types Formatting\n\n`fmt/std.h` provides formatters for:\n\n- [`std::atomic`](https://en.cppreference.com/w/cpp/atomic/atomic)\n- [`std::atomic_flag`](https://en.cppreference.com/w/cpp/atomic/atomic_flag)\n- [`std::bitset`](https://en.cppreference.com/w/cpp/utility/bitset)\n- [`std::error_code`](https://en.cppreference.com/w/cpp/error/error_code)\n- [`std::exception`](https://en.cppreference.com/w/cpp/error/exception)\n- [`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path)\n- [`std::monostate`](\n https://en.cppreference.com/w/cpp/utility/variant/monostate)\n- [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional)\n- [`std::source_location`](\n https://en.cppreference.com/w/cpp/utility/source_location)\n- [`std::thread::id`](https://en.cppreference.com/w/cpp/thread/thread/id)\n- [`std::variant`](https://en.cppreference.com/w/cpp/utility/variant/variant)\n\n::: ptr(const std::unique_ptr&)\n\n::: ptr(const std::shared_ptr&)\n\n### Variants\n\nA `std::variant` can be formatted only if every alternative is\nformattable, and requires the `__cpp_lib_variant` [library\nfeature](https://en.cppreference.com/w/cpp/feature_test).\n\n**Example**:\n\n #include \n\n fmt::print(\"{}\", std::variant('x'));\n // Output: variant('x')\n\n fmt::print(\"{}\", std::variant());\n // Output: variant(monostate)\n\n## Bit-Fields and Packed Structs\n\nTo format a bit-field or a field of a struct with `__attribute__((packed))`\napplied to it, you need to convert it to the underlying or compatible type via\na cast or a unary `+` ([godbolt](https://www.godbolt.org/z/3qKKs6T5Y)):\n\n```c++\nstruct smol {\n int bit : 1;\n};\n\nauto s = smol();\nfmt::print(\"{}\", +s.bit);\n```\n\nThis is a known limitation of \"perfect\" forwarding in C++.\n\n\n## Enum Formatting\n\n`fmt/enum.h` provides formatting of enums annotated with\n`fmt::as_identifiers`. Such an enum is formatted as the identifier of the\nenumerator matching the formatted value:\n\n #include \n\n enum class [[=fmt::as_identifiers]] color { red, green, blue };\n\n fmt::print(\"{}\", color::green);\n // Output: green\n\nSuch enums are formatted using the string [Format Specification](\nsyntax.md#format-specification), for example:\n\n fmt::print(\"[{:>7}]\", color::red);\n // Output: [ red]\n\nIdentifiers are only available as `char` strings so annotated enums are not\nformattable with other character types.\n\nIf several enumerators have the same value, the first one in the order of\ndeclaration is used. A value that doesn't match any enumerator is represented\nas its underlying value in decimal before applying string formatting:\n\n fmt::print(\"{}\", static_cast(42));\n // Output: 42\n\nAn enum annotated with `fmt::as_underlying` is instead formatted as its\nunderlying value using the integer [Format Specification](\nsyntax.md#format-specification):\n\n enum class [[=fmt::as_underlying]] color { red = 1, green = 2, blue = 4 };\n\n fmt::print(\"{:04x}\", color::blue);\n // Output: 0004\n\nSuch an enum is mapped to its underlying type before type erasure, so it can\nalso be used as dynamic width or precision. Unlike `fmt::as_identifiers`, it\nworks with all character types. The two annotations specify different\nrepresentations and cannot be combined.\n\nEnums without an annotation are not affected and are formatted as before, i.e.\nscoped enums require `format_as` or a `formatter` specialization, see\n[Formatting User-Defined Types](#udt).\n\nThis uses two C++26 features:\n[reflection](https://en.cppreference.com/w/cpp/language/operator_reflection) to\nretrieve the enumerator identifiers and\n[annotations](https://en.cppreference.com/w/cpp/language/annotations) to opt an\nenum in via `fmt::as_identifiers`. It therefore requires a compiler with\nreflection support,\nwhich may need an extra flag such as `-freflection` in GCC. The macro\n`FMT_USE_REFLECTION` is set to 1 if reflection is available and to 0 otherwise.\nIt can also be defined by the user to disable the use of reflection.\n\nWhen {fmt} is built as a module, reflection support is detected when the module\nitself is compiled, so this API is only available to importers if the module was\nbuilt with reflection enabled.\n\n\n## Compile-Time Support\n\n`fmt/compile.h` provides format string compilation and compile-time\n(`constexpr`) formatting enabled via the `FMT_COMPILE` macro or the `_cf`\nuser-defined literal defined in namespace `fmt::literals`. Format strings\nmarked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into\nefficient formatting code at compile-time. This supports arguments of built-in\nand string types as well as user-defined types with `format` methods taking\nthe format context type as a template parameter in their `formatter`\nspecializations. For example ([run](https://www.godbolt.org/z/3c13erEoq)):\n\n struct point {\n double x;\n double y;\n };\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n using namespace fmt::literals;\n std::string s = fmt::format(\"{}\"_cf, point(4, 2));\n\nFormat string compilation can generate more binary code compared to the\ndefault API and is only recommended in places where formatting is a\nperformance bottleneck.\n\nThe same APIs support formatting at compile time e.g. in `constexpr`\nand `consteval` functions. Additionally there is an experimental\n`FMT_STATIC_FORMAT` that allows formatting into a string of the exact\nrequired size at compile time. Compile-time formatting works with built-in\nand user-defined formatters that have `constexpr` `format` methods.\nExample:\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n constexpr auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n constexpr auto s = FMT_STATIC_FORMAT(\"{}\", point(4, 2));\n const char* cstr = s.c_str(); // Points the static string \"(4, 2)\".\n\n::: operator\"\"_cf\n\n::: FMT_COMPILE\n\n::: FMT_STATIC_FORMAT\n\n\n## Terminal Colors and Text Styles\n\n`fmt/color.h` provides support for terminal color and text style output.\n\n::: print(text_style, format_string, T&&...)\n\n::: fg(detail::color_type)\n\n::: bg(detail::color_type)\n\n::: styled(const T&, text_style)\n\n\n## System APIs\n\n::: ostream\n\n::: output_file(cstring_view, T...)\n\n::: windows_error\n\n\n## `std::ostream` Support\n\n`fmt/ostream.h` provides `std::ostream` support including formatting of\nuser-defined types that have an overloaded insertion operator\n(`operator<<`). In order to make a type formattable via `std::ostream`\nyou should provide a `formatter` specialization inherited from\n`ostream_formatter`:\n\n #include \n\n struct date {\n int year, month, day;\n\n friend std::ostream& operator<<(std::ostream& os, const date& d) {\n return os << d.year << '-' << d.month << '-' << d.day;\n }\n };\n\n template <> struct fmt::formatter : ostream_formatter {};\n\n std::string s = fmt::format(\"The date is {}\", date{2012, 12, 9});\n // s == \"The date is 2012-12-9\"\n\n::: streamed(const T&)\n\n::: print(std::ostream&, format_string, T&&...)\n\n\n## Dynamic Argument Lists\n\nThe header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API\nthat can be used to construct format argument lists dynamically.\n\n::: dynamic_format_arg_store\n\n\n## Safe `printf`\n\nThe header `fmt/printf.h` provides `printf`-like formatting\nfunctionality. The following functions use [printf format string\nsyntax](https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html)\nwith the POSIX extension for positional arguments. Unlike their standard\ncounterparts, the `fmt` functions are type-safe and throw an exception\nif an argument type doesn't match its format specification.\n\n::: printf(string_view, const T&...)\n\n::: fprintf(std::FILE*, string_view, const T&...)\n\n::: sprintf(string_view, const T&...)\n\n\n## Wide Strings\n\nThe optional header `fmt/xchar.h` provides support for `wchar_t` and\nexotic character types.\n\n::: wstring_view\n\n::: wformat_context\n\n::: to_wstring(const T&)\n\n## Compatibility with C++20 `std::format`\n\n{fmt} implements nearly all of the [C++20 formatting\nlibrary](https://en.cppreference.com/w/cpp/utility/format) with the\nfollowing differences:\n\n- Names are defined in the `fmt` namespace instead of `std` to avoid\n collisions with standard library implementations.\n\n- Width calculation doesn't use grapheme clusterization. The latter has\n been implemented in a separate branch but hasn't been integrated yet.\n\n- The default floating-point representation in {fmt} uses the smallest\n precision that provides round-trip guarantees similarly to other languages\n like Java and Python. `std::format` is currently specified in terms of\n `std::to_chars` which tries to generate the smallest number of characters\n (ignoring redundant digits and sign in exponent) and may produce more\n decimal digits than necessary.\n\n## Configuration Options\n\n{fmt} provides configuration via CMake options and preprocessor macros to\nenable or disable features and to optimize for binary size. For example, you\ncan disable OS-specific APIs defined in `fmt/os.h` with `-DFMT_OS=OFF` when\nconfiguring CMake.\n\n### CMake Options\n\n- **`FMT_OS`**: When set to `OFF`, disables OS-specific APIs (`fmt/os.h`).\n- **`FMT_UNICODE`**: When set to `OFF`, disables Unicode support on\n Windows/MSVC. Unicode support is always enabled on other platforms.\n\n### Macros\n\n- **`FMT_HEADER_ONLY`**: Enables the header-only mode when defined. It is an\n alternative to using the `fmt::fmt-header-only` CMake target.\n Default: not defined.\n\n- **`FMT_USE_EXCEPTIONS`**: Disables the use of exceptions when set to `0`.\n Default: `1` (`0` if compiled with `-fno-exceptions`).\n\n- **`FMT_USE_LOCALE`**: When set to `0`, disables locale support.\n Default: `1` (`0` when `FMT_OPTIMIZE_SIZE > 1`).\n\n- **`FMT_CUSTOM_ASSERT_FAIL`**: When set to `1`, allows users to provide a\n custom `fmt::assert_fail` function which is called on assertion failures and,\n if exceptions are disabled, on runtime errors. Default: `0`.\n\n- **`FMT_BUILTIN_TYPES`**: When set to `0`, disables built-in handling of\n arithmetic and string types other than `int`. This reduces library size at\n the cost of per-call overhead. Default: `1`.\n\n- **`FMT_OPTIMIZE_SIZE`**: Controls binary size optimizations:\n - `0` - off (default)\n - `1` - applies some optimizations\n - `2` - disables locale support by default, some Unicode features, and\n named arguments, and applies more aggressive optimizations\n\n### Binary Size Optimization\n\nTo minimize the binary footprint of {fmt} as much as possible at the cost of\nsome features, you can use the following configuration:\n\n- CMake options:\n - `FMT_OS=OFF`\n- Macros:\n - `FMT_BUILTIN_TYPES=0`\n - `FMT_OPTIMIZE_SIZE=2`\n"},"items":[{"name":"api.md","path":"doc/api.md","rawUrl":"https://raw.githubusercontent.com/fmtlib/fmt/HEAD/doc/api.md","title":"doc - API Interface Contract & Specifications","category":"project-spec","format":"markdown","content":"# API Reference\n\nThe {fmt} library API consists of the following components:\n\n- [`fmt/core.h`](#core-api): the core API providing main formatting functions\n for `char`/UTF-8 with C++20 compile-time checks and minimal dependencies\n- [`fmt/format.h`](#format-api): `fmt::format` and other formatting functions\n as well as locale support\n- [`fmt/ranges.h`](#ranges-api): formatting of ranges and tuples\n- [`fmt/chrono.h`](#chrono-api): date and time formatting\n- [`fmt/std.h`](#std-api): formatters for standard library types\n- [`fmt/enum.h`](#enum-api): formatting of annotated enums\n- [`fmt/compile.h`](#compile-api): format string compilation\n- [`fmt/color.h`](#color-api): terminal colors and text styles\n- [`fmt/os.h`](#os-api): system APIs\n- [`fmt/ostream.h`](#ostream-api): `std::ostream` support\n- [`fmt/args.h`](#args-api): dynamic argument lists\n- [`fmt/printf.h`](#printf-api): safe `printf`\n- [`fmt/xchar.h`](#xchar-api): optional `wchar_t` support\n\nAll functions and types provided by the library reside in namespace `fmt`\nand macros have prefix `FMT_`.\n\n## C++ Module API\n\nWith the C++ module API, the headers listed above don't need to be included.\nYou can use the `import fmt;` statement instead. All other functionality,\nlisted below, remains the same.\n\n## Core API\n\n`fmt/core.h` defines the core API which provides main formatting functions\nfor `char`/UTF-8 with C++20 compile-time checks. It has minimal include\ndependencies for better compile times. This header is only beneficial when\nusing {fmt} as a library (the default) and not in the header-only mode.\nIt also provides `formatter` specializations for the following types:\n\n- `int`, `long long`\n- `unsigned`, `unsigned long long`\n- `float`, `double`, `long double`\n- `bool`\n- `char`\n- `const char*`, [`fmt::string_view`](#basic_string_view)\n- `const void*`\n\nThe following functions use [format string syntax](syntax.md) similar to that\nof [str.format](https://docs.python.org/3/library/stdtypes.html#str.format)\nin Python. They take *fmt* and *args* as arguments.\n\n*fmt* is a format string that contains literal text and replacement fields\nsurrounded by braces `{}`. The fields are replaced with formatted arguments\nin the resulting string. [`fmt::format_string`](#format_string) is a format\nstring which can be implicitly constructed from a string literal or a\n`constexpr` string and is checked at compile time in C++20. To pass a runtime\nformat string wrap it in [`fmt::runtime`](#runtime).\n\n*args* is an argument list representing objects to be formatted.\n\nI/O errors are reported as [`std::system_error`](\nhttps://en.cppreference.com/w/cpp/error/system_error) exceptions unless\nspecified otherwise.\n\n::: print(format_string, T&&...)\n\n::: print(FILE*, format_string, T&&...)\n\n::: println(format_string, T&&...)\n\n::: println(FILE*, format_string, T&&...)\n\n::: format_to(OutputIt&&, format_string, T&&...)\n\n::: format_to_n(OutputIt, size_t, format_string, T&&...)\n\n::: format_to_n_result\n\n::: formatted_size(format_string, T&&...)\n\n\n### Formatting User-Defined Types\n\nThe {fmt} library provides formatters for many standard C++ types.\nSee [`fmt/ranges.h`](#ranges-api) for ranges and tuples including standard\ncontainers such as `std::vector`, [`fmt/chrono.h`](#chrono-api) for date and\ntime formatting and [`fmt/std.h`](#std-api) for other standard library types.\n\nThere are two ways to make a user-defined type formattable: providing a\n`format_as` function or specializing the `formatter` struct template.\nFormatting of non-void pointer types is intentionally disallowed and they\ncannot be made formattable via either extension API.\n\nUse `format_as` if you want to make your type formattable as some other\ntype with the same format specifiers. The `format_as` function should\ntake an object of your type and return an object of a formattable type.\nIt should be defined in the same namespace as your type.\n`format_as` cannot be used when a type also matches another `formatter`\nspecialization, such as the range `formatter`, because the specializations\nwould be ambiguous. Disable the conflicting specialization, if possible,\nor provide an explicit `formatter` specialization instead.\n\nExample ([run](https://godbolt.org/z/nvME4arz8)):\n\n #include \n\n namespace kevin_namespacy {\n\n enum class film {\n house_of_cards, american_beauty, se7en = 7\n };\n\n auto format_as(film f) { return fmt::underlying(f); }\n\n }\n\n int main() {\n fmt::print(\"{}\\n\", kevin_namespacy::film::se7en); // Output: 7\n }\n\nUsing a specialization is more complex, but gives you full control over\nparsing and formatting. To use this method, specialize the `formatter`\nstruct template for your type and implement `parse` and `format`\nmethods.\n\nThe recommended way of defining a formatter is by reusing an existing\none via inheritance or composition. This way you can support standard\nformat specifiers without implementing them yourself. For example:\n\n```c++\n// color.h:\n#include \n\nenum class color {red, green, blue};\n\ntemplate <> struct fmt::formatter: formatter {\n // parse is inherited from formatter.\n\n auto format(color c, format_context& ctx) const\n -> format_context::iterator;\n};\n```\n\n```c++\n// color.cc:\n#include \"color.h\"\n#include \n\nauto fmt::formatter::format(color c, format_context& ctx) const\n -> format_context::iterator {\n string_view name = \"unknown\";\n switch (c) {\n case color::red: name = \"red\"; break;\n case color::green: name = \"green\"; break;\n case color::blue: name = \"blue\"; break;\n }\n return formatter::format(name, ctx);\n}\n```\n\nNote that `formatter::format` is defined in `fmt/format.h`\nso it has to be included in the source file. Since `parse` is inherited\nfrom `formatter` it will recognize all string format\nspecifications, for example\n\n```c++\nfmt::format(\"{:>10}\", color::blue)\n```\n\nwill return `\" blue\"`.\n\n\n\nIn general the formatter has the following form:\n\n template <> struct fmt::formatter {\n // Parses format specifiers and stores them in the formatter.\n //\n // [ctx.begin(), ctx.end()) is a, possibly empty, character range that\n // contains a part of the format string starting from the format\n // specifications to be parsed, e.g. in\n //\n // fmt::format(\"{:f} continued\", ...);\n //\n // the range will contain \"f} continued\". The formatter should parse\n // specifiers until '}' or the end of the range. In this example the\n // formatter should parse the 'f' specifier and return an iterator\n // pointing to '}'.\n constexpr auto parse(format_parse_context& ctx)\n -> format_parse_context::iterator;\n\n // Formats value using the parsed format specification stored in this\n // formatter and writes the output to ctx.out().\n auto format(const T& value, format_context& ctx) const\n -> format_context::iterator;\n };\n\nIt is recommended to at least support fill, align and width that apply\nto the whole object and have the same semantics as in standard\nformatters.\n\nYou can also write a formatter for a hierarchy of classes:\n\n```c++\n// demo.h:\n#include \n#include \n\nstruct A {\n virtual ~A() {}\n virtual std::string name() const { return \"A\"; }\n};\n\nstruct B : A {\n virtual std::string name() const { return \"B\"; }\n};\n\ntemplate \nstruct fmt::formatter, char>> :\n fmt::formatter {\n auto format(const A& a, format_context& ctx) const {\n return formatter::format(a.name(), ctx);\n }\n};\n```\n\n```c++\n// demo.cc:\n#include \"demo.h\"\n#include \n\nint main() {\n B b;\n A& a = b;\n fmt::print(\"{}\", a); // Output: B\n}\n```\n\nProviding both a `formatter` specialization and a `format_as` overload is\ndisallowed.\n\n::: basic_format_parse_context\n\n::: context\n\n::: format_context\n\n### Compile-Time Checks\n\nCompile-time format string checks are enabled by default on compilers\nthat support C++20 `consteval`. On older compilers you can use the\n[FMT_STRING](#legacy-checks) macro defined in `fmt/format.h` instead.\n\nUnused arguments are allowed as in Python's `str.format` and ordinary functions.\n\nSee [Type Erasure](#type-erasure) for an example of how to enable compile-time\nchecks in your own functions with `fmt::format_string` while avoiding template\nbloat.\n\n::: fstring\n\n::: format_string\n\n::: runtime(string_view)\n\n### Type Erasure\n\nYou can create your own formatting function with compile-time checks and\nsmall binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):\n\n```c++\n#include \n\nvoid vlog(const char* file, int line,\n fmt::string_view fmt, fmt::format_args args) {\n fmt::print(\"{}: {}: {}\", file, line, fmt::vformat(fmt, args));\n}\n\ntemplate \nvoid log(const char* file, int line,\n fmt::format_string fmt, T&&... args) {\n vlog(file, line, fmt, fmt::make_format_args(args...));\n}\n\n#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)\n\nMY_LOG(\"invalid squishiness: {}\", 42);\n```\n\nNote that `vlog` is not parameterized on argument types which improves\ncompile times and reduces binary code size compared to a fully\nparameterized version.\n\n::: make_format_args(T&...)\n\n::: basic_format_args\n\n::: format_args\n\n::: basic_format_arg\n\n### Named Arguments\n\n::: arg(const char*, const T&)\n\n### Compatibility\n\n::: basic_string_view\n\n::: string_view\n\n## Format API\n\n`fmt/format.h` defines the full format API providing additional\nformatting functions and locale support.\n\n\n::: format(format_string, T&&...)\n\n::: vformat(string_view, format_args)\n\n::: operator\"\"_a()\n\n### Utilities\n\n::: ptr(T)\n\n::: underlying(Enum)\n\n::: to_string(const T&)\n\n::: group_digits(T)\n\n::: detail::buffer\n\n::: basic_memory_buffer\n\n### System Errors\n\n{fmt} does not use `errno` to communicate errors to the user, but it may\ncall system functions which set `errno`. Users should not make any\nassumptions about the value of `errno` being preserved by library\nfunctions.\n\n::: system_error\n\n::: format_system_error\n\n### Custom Allocators\n\nThe {fmt} library supports custom dynamic memory allocators. A custom\nallocator class can be specified as a template argument to\n[`fmt::basic_memory_buffer`](#basic_memory_buffer):\n\n using custom_memory_buffer = \n fmt::basic_memory_buffer;\n\nIt is also possible to write a formatting function that uses a custom\nallocator:\n\n using custom_string =\n std::basic_string, custom_allocator>;\n\n auto vformat(custom_allocator alloc, fmt::string_view fmt,\n fmt::format_args args) -> custom_string {\n auto buf = custom_memory_buffer(alloc);\n fmt::vformat_to(std::back_inserter(buf), fmt, args);\n return custom_string(buf.data(), buf.size(), alloc);\n }\n\n template \n auto format(custom_allocator alloc, fmt::string_view fmt,\n const Args& ... args) -> custom_string {\n return vformat(alloc, fmt, fmt::make_format_args(args...));\n }\n\nThe allocator will be used for the output container only. Formatting\nfunctions normally don't do any allocations for built-in and string\ntypes except for non-default floating-point formatting that occasionally\nfalls back on `sprintf`.\n\n### Locale\n\nAll formatting is locale-independent by default. Use the `'L'` format\nspecifier to insert the appropriate number separator characters from the\nlocale:\n\n #include \n #include \n\n std::locale::global(std::locale(\"en_US.UTF-8\"));\n auto s = fmt::format(\"{:L}\", 1000000); // s == \"1,000,000\"\n\n`fmt/format.h` provides the following overloads of formatting functions\nthat take `std::locale` as a parameter. The locale type is a template\nparameter to avoid the expensive `` include.\n\n::: format(locale_ref, format_string, T&&...)\n\n::: format_to(OutputIt, locale_ref, format_string, T&&...)\n\n::: formatted_size(locale_ref, format_string, T&&...)\n\n\n### Legacy Compile-Time Checks\n\n`FMT_STRING` enables compile-time checks on older compilers. It requires\nC++14 or later and is a no-op in C++11.\n\n::: FMT_STRING\n\nTo force the use of legacy compile-time checks, define the preprocessor\nvariable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting\n`FMT_STRING` will fail to compile with regular strings.\n\n\n## Range and Tuple Formatting\n\n`fmt/ranges.h` provides formatting support for ranges and tuples:\n\n #include \n\n fmt::print(\"{}\", std::tuple{'a', 42});\n // Output: ('a', 42)\n\nUsing `fmt::join`, you can separate tuple elements with a custom separator:\n\n #include \n\n auto t = std::tuple{1, 'a'};\n fmt::print(\"{}\", fmt::join(t, \", \"));\n // Output: 1, a\n\n::: join(Range&&, string_view)\n\n::: join(It, Sentinel, string_view)\n\n::: join(std::initializer_list, string_view)\n\n\n## Date and Time Formatting\n\n`fmt/chrono.h` provides formatters for\n\n- [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)\n- [`std::chrono::time_point`](\n https://en.cppreference.com/w/cpp/chrono/time_point)\n- [`std::tm`](https://en.cppreference.com/w/cpp/chrono/c/tm)\n\nThe format syntax is described in [Chrono Format Specifications](syntax.md#\nchrono-format-spec).\n\n**Example**:\n\n #include \n\n int main() {\n auto now = std::chrono::system_clock::now();\n\n fmt::print(\"The date is {:%Y-%m-%d}.\\n\", now);\n // Output: The date is 2020-11-07.\n // (with 2020-11-07 replaced by the current date)\n\n using namespace std::literals::chrono_literals;\n\n fmt::print(\"Default format: {} {}\\n\", 42s, 100ms);\n // Output: Default format: 42s 100ms\n\n fmt::print(\"strftime-like format: {:%H:%M:%S}\\n\", 3h + 15min + 30s);\n // Output: strftime-like format: 03:15:30\n }\n\n::: gmtime(std::time_t)\n\n\n## Standard Library Types Formatting\n\n`fmt/std.h` provides formatters for:\n\n- [`std::atomic`](https://en.cppreference.com/w/cpp/atomic/atomic)\n- [`std::atomic_flag`](https://en.cppreference.com/w/cpp/atomic/atomic_flag)\n- [`std::bitset`](https://en.cppreference.com/w/cpp/utility/bitset)\n- [`std::error_code`](https://en.cppreference.com/w/cpp/error/error_code)\n- [`std::exception`](https://en.cppreference.com/w/cpp/error/exception)\n- [`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path)\n- [`std::monostate`](\n https://en.cppreference.com/w/cpp/utility/variant/monostate)\n- [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional)\n- [`std::source_location`](\n https://en.cppreference.com/w/cpp/utility/source_location)\n- [`std::thread::id`](https://en.cppreference.com/w/cpp/thread/thread/id)\n- [`std::variant`](https://en.cppreference.com/w/cpp/utility/variant/variant)\n\n::: ptr(const std::unique_ptr&)\n\n::: ptr(const std::shared_ptr&)\n\n### Variants\n\nA `std::variant` can be formatted only if every alternative is\nformattable, and requires the `__cpp_lib_variant` [library\nfeature](https://en.cppreference.com/w/cpp/feature_test).\n\n**Example**:\n\n #include \n\n fmt::print(\"{}\", std::variant('x'));\n // Output: variant('x')\n\n fmt::print(\"{}\", std::variant());\n // Output: variant(monostate)\n\n## Bit-Fields and Packed Structs\n\nTo format a bit-field or a field of a struct with `__attribute__((packed))`\napplied to it, you need to convert it to the underlying or compatible type via\na cast or a unary `+` ([godbolt](https://www.godbolt.org/z/3qKKs6T5Y)):\n\n```c++\nstruct smol {\n int bit : 1;\n};\n\nauto s = smol();\nfmt::print(\"{}\", +s.bit);\n```\n\nThis is a known limitation of \"perfect\" forwarding in C++.\n\n\n## Enum Formatting\n\n`fmt/enum.h` provides formatting of enums annotated with\n`fmt::as_identifiers`. Such an enum is formatted as the identifier of the\nenumerator matching the formatted value:\n\n #include \n\n enum class [[=fmt::as_identifiers]] color { red, green, blue };\n\n fmt::print(\"{}\", color::green);\n // Output: green\n\nSuch enums are formatted using the string [Format Specification](\nsyntax.md#format-specification), for example:\n\n fmt::print(\"[{:>7}]\", color::red);\n // Output: [ red]\n\nIdentifiers are only available as `char` strings so annotated enums are not\nformattable with other character types.\n\nIf several enumerators have the same value, the first one in the order of\ndeclaration is used. A value that doesn't match any enumerator is represented\nas its underlying value in decimal before applying string formatting:\n\n fmt::print(\"{}\", static_cast(42));\n // Output: 42\n\nAn enum annotated with `fmt::as_underlying` is instead formatted as its\nunderlying value using the integer [Format Specification](\nsyntax.md#format-specification):\n\n enum class [[=fmt::as_underlying]] color { red = 1, green = 2, blue = 4 };\n\n fmt::print(\"{:04x}\", color::blue);\n // Output: 0004\n\nSuch an enum is mapped to its underlying type before type erasure, so it can\nalso be used as dynamic width or precision. Unlike `fmt::as_identifiers`, it\nworks with all character types. The two annotations specify different\nrepresentations and cannot be combined.\n\nEnums without an annotation are not affected and are formatted as before, i.e.\nscoped enums require `format_as` or a `formatter` specialization, see\n[Formatting User-Defined Types](#udt).\n\nThis uses two C++26 features:\n[reflection](https://en.cppreference.com/w/cpp/language/operator_reflection) to\nretrieve the enumerator identifiers and\n[annotations](https://en.cppreference.com/w/cpp/language/annotations) to opt an\nenum in via `fmt::as_identifiers`. It therefore requires a compiler with\nreflection support,\nwhich may need an extra flag such as `-freflection` in GCC. The macro\n`FMT_USE_REFLECTION` is set to 1 if reflection is available and to 0 otherwise.\nIt can also be defined by the user to disable the use of reflection.\n\nWhen {fmt} is built as a module, reflection support is detected when the module\nitself is compiled, so this API is only available to importers if the module was\nbuilt with reflection enabled.\n\n\n## Compile-Time Support\n\n`fmt/compile.h` provides format string compilation and compile-time\n(`constexpr`) formatting enabled via the `FMT_COMPILE` macro or the `_cf`\nuser-defined literal defined in namespace `fmt::literals`. Format strings\nmarked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into\nefficient formatting code at compile-time. This supports arguments of built-in\nand string types as well as user-defined types with `format` methods taking\nthe format context type as a template parameter in their `formatter`\nspecializations. For example ([run](https://www.godbolt.org/z/3c13erEoq)):\n\n struct point {\n double x;\n double y;\n };\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n using namespace fmt::literals;\n std::string s = fmt::format(\"{}\"_cf, point(4, 2));\n\nFormat string compilation can generate more binary code compared to the\ndefault API and is only recommended in places where formatting is a\nperformance bottleneck.\n\nThe same APIs support formatting at compile time e.g. in `constexpr`\nand `consteval` functions. Additionally there is an experimental\n`FMT_STATIC_FORMAT` that allows formatting into a string of the exact\nrequired size at compile time. Compile-time formatting works with built-in\nand user-defined formatters that have `constexpr` `format` methods.\nExample:\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n constexpr auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n constexpr auto s = FMT_STATIC_FORMAT(\"{}\", point(4, 2));\n const char* cstr = s.c_str(); // Points the static string \"(4, 2)\".\n\n::: operator\"\"_cf\n\n::: FMT_COMPILE\n\n::: FMT_STATIC_FORMAT\n\n\n## Terminal Colors and Text Styles\n\n`fmt/color.h` provides support for terminal color and text style output.\n\n::: print(text_style, format_string, T&&...)\n\n::: fg(detail::color_type)\n\n::: bg(detail::color_type)\n\n::: styled(const T&, text_style)\n\n\n## System APIs\n\n::: ostream\n\n::: output_file(cstring_view, T...)\n\n::: windows_error\n\n\n## `std::ostream` Support\n\n`fmt/ostream.h` provides `std::ostream` support including formatting of\nuser-defined types that have an overloaded insertion operator\n(`operator<<`). In order to make a type formattable via `std::ostream`\nyou should provide a `formatter` specialization inherited from\n`ostream_formatter`:\n\n #include \n\n struct date {\n int year, month, day;\n\n friend std::ostream& operator<<(std::ostream& os, const date& d) {\n return os << d.year << '-' << d.month << '-' << d.day;\n }\n };\n\n template <> struct fmt::formatter : ostream_formatter {};\n\n std::string s = fmt::format(\"The date is {}\", date{2012, 12, 9});\n // s == \"The date is 2012-12-9\"\n\n::: streamed(const T&)\n\n::: print(std::ostream&, format_string, T&&...)\n\n\n## Dynamic Argument Lists\n\nThe header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API\nthat can be used to construct format argument lists dynamically.\n\n::: dynamic_format_arg_store\n\n\n## Safe `printf`\n\nThe header `fmt/printf.h` provides `printf`-like formatting\nfunctionality. The following functions use [printf format string\nsyntax](https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html)\nwith the POSIX extension for positional arguments. Unlike their standard\ncounterparts, the `fmt` functions are type-safe and throw an exception\nif an argument type doesn't match its format specification.\n\n::: printf(string_view, const T&...)\n\n::: fprintf(std::FILE*, string_view, const T&...)\n\n::: sprintf(string_view, const T&...)\n\n\n## Wide Strings\n\nThe optional header `fmt/xchar.h` provides support for `wchar_t` and\nexotic character types.\n\n::: wstring_view\n\n::: wformat_context\n\n::: to_wstring(const T&)\n\n## Compatibility with C++20 `std::format`\n\n{fmt} implements nearly all of the [C++20 formatting\nlibrary](https://en.cppreference.com/w/cpp/utility/format) with the\nfollowing differences:\n\n- Names are defined in the `fmt` namespace instead of `std` to avoid\n collisions with standard library implementations.\n\n- Width calculation doesn't use grapheme clusterization. The latter has\n been implemented in a separate branch but hasn't been integrated yet.\n\n- The default floating-point representation in {fmt} uses the smallest\n precision that provides round-trip guarantees similarly to other languages\n like Java and Python. `std::format` is currently specified in terms of\n `std::to_chars` which tries to generate the smallest number of characters\n (ignoring redundant digits and sign in exponent) and may produce more\n decimal digits than necessary.\n\n## Configuration Options\n\n{fmt} provides configuration via CMake options and preprocessor macros to\nenable or disable features and to optimize for binary size. For example, you\ncan disable OS-specific APIs defined in `fmt/os.h` with `-DFMT_OS=OFF` when\nconfiguring CMake.\n\n### CMake Options\n\n- **`FMT_OS`**: When set to `OFF`, disables OS-specific APIs (`fmt/os.h`).\n- **`FMT_UNICODE`**: When set to `OFF`, disables Unicode support on\n Windows/MSVC. Unicode support is always enabled on other platforms.\n\n### Macros\n\n- **`FMT_HEADER_ONLY`**: Enables the header-only mode when defined. It is an\n alternative to using the `fmt::fmt-header-only` CMake target.\n Default: not defined.\n\n- **`FMT_USE_EXCEPTIONS`**: Disables the use of exceptions when set to `0`.\n Default: `1` (`0` if compiled with `-fno-exceptions`).\n\n- **`FMT_USE_LOCALE`**: When set to `0`, disables locale support.\n Default: `1` (`0` when `FMT_OPTIMIZE_SIZE > 1`).\n\n- **`FMT_CUSTOM_ASSERT_FAIL`**: When set to `1`, allows users to provide a\n custom `fmt::assert_fail` function which is called on assertion failures and,\n if exceptions are disabled, on runtime errors. Default: `0`.\n\n- **`FMT_BUILTIN_TYPES`**: When set to `0`, disables built-in handling of\n arithmetic and string types other than `int`. This reduces library size at\n the cost of per-call overhead. Default: `1`.\n\n- **`FMT_OPTIMIZE_SIZE`**: Controls binary size optimizations:\n - `0` - off (default)\n - `1` - applies some optimizations\n - `2` - disables locale support by default, some Unicode features, and\n named arguments, and applies more aggressive optimizations\n\n### Binary Size Optimization\n\nTo minimize the binary footprint of {fmt} as much as possible at the cost of\nsome features, you can use the following configuration:\n\n- CMake options:\n - `FMT_OS=OFF`\n- Macros:\n - `FMT_BUILTIN_TYPES=0`\n - `FMT_OPTIMIZE_SIZE=2`\n","isInternal":false,"tokens":6493,"sizeBytes":26172}],"systemPromptSnippet":"\n\n# API Reference\n\nThe {fmt} library API consists of the following components:\n\n- [`fmt/core.h`](#core-api): the core API providing main formatting functions\n for `char`/UTF-8 with C++20 compile-time checks and minimal dependencies\n- [`fmt/format.h`](#format-api): `fmt::format` and other formatting functions\n as well as locale support\n- [`fmt/ranges.h`](#ranges-api): formatting of ranges and tuples\n- [`fmt/chrono.h`](#chrono-api): date and time formatting\n- [`fmt/std.h`](#std-api): formatters for standard library types\n- [`fmt/enum.h`](#enum-api): formatting of annotated enums\n- [`fmt/compile.h`](#compile-api): format string compilation\n- [`fmt/color.h`](#color-api): terminal colors and text styles\n- [`fmt/os.h`](#os-api): system APIs\n- [`fmt/ostream.h`](#ostream-api): `std::ostream` support\n- [`fmt/args.h`](#args-api): dynamic argument lists\n- [`fmt/printf.h`](#printf-api): safe `printf`\n- [`fmt/xchar.h`](#xchar-api): optional `wchar_t` support\n\nAll functions and types provided by the library reside in namespace `fmt`\nand macros have prefix `FMT_`.\n\n## C++ Module API\n\nWith the C++ module API, the headers listed above don't need to be included.\nYou can use the `import fmt;` statement instead. All other functionality,\nlisted below, remains the same.\n\n## Core API\n\n`fmt/core.h` defines the core API which provides main formatting functions\nfor `char`/UTF-8 with C++20 compile-time checks. It has minimal include\ndependencies for better compile times. This header is only beneficial when\nusing {fmt} as a library (the default) and not in the header-only mode.\nIt also provides `formatter` specializations for the following types:\n\n- `int`, `long long`\n- `unsigned`, `unsigned long long`\n- `float`, `double`, `long double`\n- `bool`\n- `char`\n- `const char*`, [`fmt::string_view`](#basic_string_view)\n- `const void*`\n\nThe following functions use [format string syntax](syntax.md) similar to that\nof [str.format](https://docs.python.org/3/library/stdtypes.html#str.format)\nin Python. They take *fmt* and *args* as arguments.\n\n*fmt* is a format string that contains literal text and replacement fields\nsurrounded by braces `{}`. The fields are replaced with formatted arguments\nin the resulting string. [`fmt::format_string`](#format_string) is a format\nstring which can be implicitly constructed from a string literal or a\n`constexpr` string and is checked at compile time in C++20. To pass a runtime\nformat string wrap it in [`fmt::runtime`](#runtime).\n\n*args* is an argument list representing objects to be formatted.\n\nI/O errors are reported as [`std::system_error`](\nhttps://en.cppreference.com/w/cpp/error/system_error) exceptions unless\nspecified otherwise.\n\n::: print(format_string, T&&...)\n\n::: print(FILE*, format_string, T&&...)\n\n::: println(format_string, T&&...)\n\n::: println(FILE*, format_string, T&&...)\n\n::: format_to(OutputIt&&, format_string, T&&...)\n\n::: format_to_n(OutputIt, size_t, format_string, T&&...)\n\n::: format_to_n_result\n\n::: formatted_size(format_string, T&&...)\n\n\n### Formatting User-Defined Types\n\nThe {fmt} library provides formatters for many standard C++ types.\nSee [`fmt/ranges.h`](#ranges-api) for ranges and tuples including standard\ncontainers such as `std::vector`, [`fmt/chrono.h`](#chrono-api) for date and\ntime formatting and [`fmt/std.h`](#std-api) for other standard library types.\n\nThere are two ways to make a user-defined type formattable: providing a\n`format_as` function or specializing the `formatter` struct template.\nFormatting of non-void pointer types is intentionally disallowed and they\ncannot be made formattable via either extension API.\n\nUse `format_as` if you want to make your type formattable as some other\ntype with the same format specifiers. The `format_as` function should\ntake an object of your type and return an object of a formattable type.\nIt should be defined in the same namespace as your type.\n`format_as` cannot be used when a type also matches another `formatter`\nspecialization, such as the range `formatter`, because the specializations\nwould be ambiguous. Disable the conflicting specialization, if possible,\nor provide an explicit `formatter` specialization instead.\n\nExample ([run](https://godbolt.org/z/nvME4arz8)):\n\n #include \n\n namespace kevin_namespacy {\n\n enum class film {\n house_of_cards, american_beauty, se7en = 7\n };\n\n auto format_as(film f) { return fmt::underlying(f); }\n\n }\n\n int main() {\n fmt::print(\"{}\\n\", kevin_namespacy::film::se7en); // Output: 7\n }\n\nUsing a specialization is more complex, but gives you full control over\nparsing and formatting. To use this method, specialize the `formatter`\nstruct template for your type and implement `parse` and `format`\nmethods.\n\nThe recommended way of defining a formatter is by reusing an existing\none via inheritance or composition. This way you can support standard\nformat specifiers without implementing them yourself. For example:\n\n```c++\n// color.h:\n#include \n\nenum class color {red, green, blue};\n\ntemplate <> struct fmt::formatter: formatter {\n // parse is inherited from formatter.\n\n auto format(color c, format_context& ctx) const\n -> format_context::iterator;\n};\n```\n\n```c++\n// color.cc:\n#include \"color.h\"\n#include \n\nauto fmt::formatter::format(color c, format_context& ctx) const\n -> format_context::iterator {\n string_view name = \"unknown\";\n switch (c) {\n case color::red: name = \"red\"; break;\n case color::green: name = \"green\"; break;\n case color::blue: name = \"blue\"; break;\n }\n return formatter::format(name, ctx);\n}\n```\n\nNote that `formatter::format` is defined in `fmt/format.h`\nso it has to be included in the source file. Since `parse` is inherited\nfrom `formatter` it will recognize all string format\nspecifications, for example\n\n```c++\nfmt::format(\"{:>10}\", color::blue)\n```\n\nwill return `\" blue\"`.\n\n\n\nIn general the formatter has the following form:\n\n template <> struct fmt::formatter {\n // Parses format specifiers and stores them in the formatter.\n //\n // [ctx.begin(), ctx.end()) is a, possibly empty, character range that\n // contains a part of the format string starting from the format\n // specifications to be parsed, e.g. in\n //\n // fmt::format(\"{:f} continued\", ...);\n //\n // the range will contain \"f} continued\". The formatter should parse\n // specifiers until '}' or the end of the range. In this example the\n // formatter should parse the 'f' specifier and return an iterator\n // pointing to '}'.\n constexpr auto parse(format_parse_context& ctx)\n -> format_parse_context::iterator;\n\n // Formats value using the parsed format specification stored in this\n // formatter and writes the output to ctx.out().\n auto format(const T& value, format_context& ctx) const\n -> format_context::iterator;\n };\n\nIt is recommended to at least support fill, align and width that apply\nto the whole object and have the same semantics as in standard\nformatters.\n\nYou can also write a formatter for a hierarchy of classes:\n\n```c++\n// demo.h:\n#include \n#include \n\nstruct A {\n virtual ~A() {}\n virtual std::string name() const { return \"A\"; }\n};\n\nstruct B : A {\n virtual std::string name() const { return \"B\"; }\n};\n\ntemplate \nstruct fmt::formatter, char>> :\n fmt::formatter {\n auto format(const A& a, format_context& ctx) const {\n return formatter::format(a.name(), ctx);\n }\n};\n```\n\n```c++\n// demo.cc:\n#include \"demo.h\"\n#include \n\nint main() {\n B b;\n A& a = b;\n fmt::print(\"{}\", a); // Output: B\n}\n```\n\nProviding both a `formatter` specialization and a `format_as` overload is\ndisallowed.\n\n::: basic_format_parse_context\n\n::: context\n\n::: format_context\n\n### Compile-Time Checks\n\nCompile-time format string checks are enabled by default on compilers\nthat support C++20 `consteval`. On older compilers you can use the\n[FMT_STRING](#legacy-checks) macro defined in `fmt/format.h` instead.\n\nUnused arguments are allowed as in Python's `str.format` and ordinary functions.\n\nSee [Type Erasure](#type-erasure) for an example of how to enable compile-time\nchecks in your own functions with `fmt::format_string` while avoiding template\nbloat.\n\n::: fstring\n\n::: format_string\n\n::: runtime(string_view)\n\n### Type Erasure\n\nYou can create your own formatting function with compile-time checks and\nsmall binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):\n\n```c++\n#include \n\nvoid vlog(const char* file, int line,\n fmt::string_view fmt, fmt::format_args args) {\n fmt::print(\"{}: {}: {}\", file, line, fmt::vformat(fmt, args));\n}\n\ntemplate \nvoid log(const char* file, int line,\n fmt::format_string fmt, T&&... args) {\n vlog(file, line, fmt, fmt::make_format_args(args...));\n}\n\n#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)\n\nMY_LOG(\"invalid squishiness: {}\", 42);\n```\n\nNote that `vlog` is not parameterized on argument types which improves\ncompile times and reduces binary code size compared to a fully\nparameterized version.\n\n::: make_format_args(T&...)\n\n::: basic_format_args\n\n::: format_args\n\n::: basic_format_arg\n\n### Named Arguments\n\n::: arg(const char*, const T&)\n\n### Compatibility\n\n::: basic_string_view\n\n::: string_view\n\n## Format API\n\n`fmt/format.h` defines the full format API providing additional\nformatting functions and locale support.\n\n\n::: format(format_string, T&&...)\n\n::: vformat(string_view, format_args)\n\n::: operator\"\"_a()\n\n### Utilities\n\n::: ptr(T)\n\n::: underlying(Enum)\n\n::: to_string(const T&)\n\n::: group_digits(T)\n\n::: detail::buffer\n\n::: basic_memory_buffer\n\n### System Errors\n\n{fmt} does not use `errno` to communicate errors to the user, but it may\ncall system functions which set `errno`. Users should not make any\nassumptions about the value of `errno` being preserved by library\nfunctions.\n\n::: system_error\n\n::: format_system_error\n\n### Custom Allocators\n\nThe {fmt} library supports custom dynamic memory allocators. A custom\nallocator class can be specified as a template argument to\n[`fmt::basic_memory_buffer`](#basic_memory_buffer):\n\n using custom_memory_buffer = \n fmt::basic_memory_buffer;\n\nIt is also possible to write a formatting function that uses a custom\nallocator:\n\n using custom_string =\n std::basic_string, custom_allocator>;\n\n auto vformat(custom_allocator alloc, fmt::string_view fmt,\n fmt::format_args args) -> custom_string {\n auto buf = custom_memory_buffer(alloc);\n fmt::vformat_to(std::back_inserter(buf), fmt, args);\n return custom_string(buf.data(), buf.size(), alloc);\n }\n\n template \n auto format(custom_allocator alloc, fmt::string_view fmt,\n const Args& ... args) -> custom_string {\n return vformat(alloc, fmt, fmt::make_format_args(args...));\n }\n\nThe allocator will be used for the output container only. Formatting\nfunctions normally don't do any allocations for built-in and string\ntypes except for non-default floating-point formatting that occasionally\nfalls back on `sprintf`.\n\n### Locale\n\nAll formatting is locale-independent by default. Use the `'L'` format\nspecifier to insert the appropriate number separator characters from the\nlocale:\n\n #include \n #include \n\n std::locale::global(std::locale(\"en_US.UTF-8\"));\n auto s = fmt::format(\"{:L}\", 1000000); // s == \"1,000,000\"\n\n`fmt/format.h` provides the following overloads of formatting functions\nthat take `std::locale` as a parameter. The locale type is a template\nparameter to avoid the expensive `` include.\n\n::: format(locale_ref, format_string, T&&...)\n\n::: format_to(OutputIt, locale_ref, format_string, T&&...)\n\n::: formatted_size(locale_ref, format_string, T&&...)\n\n\n### Legacy Compile-Time Checks\n\n`FMT_STRING` enables compile-time checks on older compilers. It requires\nC++14 or later and is a no-op in C++11.\n\n::: FMT_STRING\n\nTo force the use of legacy compile-time checks, define the preprocessor\nvariable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting\n`FMT_STRING` will fail to compile with regular strings.\n\n\n## Range and Tuple Formatting\n\n`fmt/ranges.h` provides formatting support for ranges and tuples:\n\n #include \n\n fmt::print(\"{}\", std::tuple{'a', 42});\n // Output: ('a', 42)\n\nUsing `fmt::join`, you can separate tuple elements with a custom separator:\n\n #include \n\n auto t = std::tuple{1, 'a'};\n fmt::print(\"{}\", fmt::join(t, \", \"));\n // Output: 1, a\n\n::: join(Range&&, string_view)\n\n::: join(It, Sentinel, string_view)\n\n::: join(std::initializer_list, string_view)\n\n\n## Date and Time Formatting\n\n`fmt/chrono.h` provides formatters for\n\n- [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)\n- [`std::chrono::time_point`](\n https://en.cppreference.com/w/cpp/chrono/time_point)\n- [`std::tm`](https://en.cppreference.com/w/cpp/chrono/c/tm)\n\nThe format syntax is described in [Chrono Format Specifications](syntax.md#\nchrono-format-spec).\n\n**Example**:\n\n #include \n\n int main() {\n auto now = std::chrono::system_clock::now();\n\n fmt::print(\"The date is {:%Y-%m-%d}.\\n\", now);\n // Output: The date is 2020-11-07.\n // (with 2020-11-07 replaced by the current date)\n\n using namespace std::literals::chrono_literals;\n\n fmt::print(\"Default format: {} {}\\n\", 42s, 100ms);\n // Output: Default format: 42s 100ms\n\n fmt::print(\"strftime-like format: {:%H:%M:%S}\\n\", 3h + 15min + 30s);\n // Output: strftime-like format: 03:15:30\n }\n\n::: gmtime(std::time_t)\n\n\n## Standard Library Types Formatting\n\n`fmt/std.h` provides formatters for:\n\n- [`std::atomic`](https://en.cppreference.com/w/cpp/atomic/atomic)\n- [`std::atomic_flag`](https://en.cppreference.com/w/cpp/atomic/atomic_flag)\n- [`std::bitset`](https://en.cppreference.com/w/cpp/utility/bitset)\n- [`std::error_code`](https://en.cppreference.com/w/cpp/error/error_code)\n- [`std::exception`](https://en.cppreference.com/w/cpp/error/exception)\n- [`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path)\n- [`std::monostate`](\n https://en.cppreference.com/w/cpp/utility/variant/monostate)\n- [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional)\n- [`std::source_location`](\n https://en.cppreference.com/w/cpp/utility/source_location)\n- [`std::thread::id`](https://en.cppreference.com/w/cpp/thread/thread/id)\n- [`std::variant`](https://en.cppreference.com/w/cpp/utility/variant/variant)\n\n::: ptr(const std::unique_ptr&)\n\n::: ptr(const std::shared_ptr&)\n\n### Variants\n\nA `std::variant` can be formatted only if every alternative is\nformattable, and requires the `__cpp_lib_variant` [library\nfeature](https://en.cppreference.com/w/cpp/feature_test).\n\n**Example**:\n\n #include \n\n fmt::print(\"{}\", std::variant('x'));\n // Output: variant('x')\n\n fmt::print(\"{}\", std::variant());\n // Output: variant(monostate)\n\n## Bit-Fields and Packed Structs\n\nTo format a bit-field or a field of a struct with `__attribute__((packed))`\napplied to it, you need to convert it to the underlying or compatible type via\na cast or a unary `+` ([godbolt](https://www.godbolt.org/z/3qKKs6T5Y)):\n\n```c++\nstruct smol {\n int bit : 1;\n};\n\nauto s = smol();\nfmt::print(\"{}\", +s.bit);\n```\n\nThis is a known limitation of \"perfect\" forwarding in C++.\n\n\n## Enum Formatting\n\n`fmt/enum.h` provides formatting of enums annotated with\n`fmt::as_identifiers`. Such an enum is formatted as the identifier of the\nenumerator matching the formatted value:\n\n #include \n\n enum class [[=fmt::as_identifiers]] color { red, green, blue };\n\n fmt::print(\"{}\", color::green);\n // Output: green\n\nSuch enums are formatted using the string [Format Specification](\nsyntax.md#format-specification), for example:\n\n fmt::print(\"[{:>7}]\", color::red);\n // Output: [ red]\n\nIdentifiers are only available as `char` strings so annotated enums are not\nformattable with other character types.\n\nIf several enumerators have the same value, the first one in the order of\ndeclaration is used. A value that doesn't match any enumerator is represented\nas its underlying value in decimal before applying string formatting:\n\n fmt::print(\"{}\", static_cast(42));\n // Output: 42\n\nAn enum annotated with `fmt::as_underlying` is instead formatted as its\nunderlying value using the integer [Format Specification](\nsyntax.md#format-specification):\n\n enum class [[=fmt::as_underlying]] color { red = 1, green = 2, blue = 4 };\n\n fmt::print(\"{:04x}\", color::blue);\n // Output: 0004\n\nSuch an enum is mapped to its underlying type before type erasure, so it can\nalso be used as dynamic width or precision. Unlike `fmt::as_identifiers`, it\nworks with all character types. The two annotations specify different\nrepresentations and cannot be combined.\n\nEnums without an annotation are not affected and are formatted as before, i.e.\nscoped enums require `format_as` or a `formatter` specialization, see\n[Formatting User-Defined Types](#udt).\n\nThis uses two C++26 features:\n[reflection](https://en.cppreference.com/w/cpp/language/operator_reflection) to\nretrieve the enumerator identifiers and\n[annotations](https://en.cppreference.com/w/cpp/language/annotations) to opt an\nenum in via `fmt::as_identifiers`. It therefore requires a compiler with\nreflection support,\nwhich may need an extra flag such as `-freflection` in GCC. The macro\n`FMT_USE_REFLECTION` is set to 1 if reflection is available and to 0 otherwise.\nIt can also be defined by the user to disable the use of reflection.\n\nWhen {fmt} is built as a module, reflection support is detected when the module\nitself is compiled, so this API is only available to importers if the module was\nbuilt with reflection enabled.\n\n\n## Compile-Time Support\n\n`fmt/compile.h` provides format string compilation and compile-time\n(`constexpr`) formatting enabled via the `FMT_COMPILE` macro or the `_cf`\nuser-defined literal defined in namespace `fmt::literals`. Format strings\nmarked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into\nefficient formatting code at compile-time. This supports arguments of built-in\nand string types as well as user-defined types with `format` methods taking\nthe format context type as a template parameter in their `formatter`\nspecializations. For example ([run](https://www.godbolt.org/z/3c13erEoq)):\n\n struct point {\n double x;\n double y;\n };\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n using namespace fmt::literals;\n std::string s = fmt::format(\"{}\"_cf, point(4, 2));\n\nFormat string compilation can generate more binary code compared to the\ndefault API and is only recommended in places where formatting is a\nperformance bottleneck.\n\nThe same APIs support formatting at compile time e.g. in `constexpr`\nand `consteval` functions. Additionally there is an experimental\n`FMT_STATIC_FORMAT` that allows formatting into a string of the exact\nrequired size at compile time. Compile-time formatting works with built-in\nand user-defined formatters that have `constexpr` `format` methods.\nExample:\n\n template <> struct fmt::formatter {\n constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }\n\n template \n constexpr auto format(const point& p, FormatContext& ctx) const {\n return format_to(ctx.out(), \"({}, {})\"_cf, p.x, p.y);\n }\n };\n\n constexpr auto s = FMT_STATIC_FORMAT(\"{}\", point(4, 2));\n const char* cstr = s.c_str(); // Points the static string \"(4, 2)\".\n\n::: operator\"\"_cf\n\n::: FMT_COMPILE\n\n::: FMT_STATIC_FORMAT\n\n\n## Terminal Colors and Text Styles\n\n`fmt/color.h` provides support for terminal color and text style output.\n\n::: print(text_style, format_string, T&&...)\n\n::: fg(detail::color_type)\n\n::: bg(detail::color_type)\n\n::: styled(const T&, text_style)\n\n\n## System APIs\n\n::: ostream\n\n::: output_file(cstring_view, T...)\n\n::: windows_error\n\n\n## `std::ostream` Support\n\n`fmt/ostream.h` provides `std::ostream` support including formatting of\nuser-defined types that have an overloaded insertion operator\n(`operator<<`). In order to make a type formattable via `std::ostream`\nyou should provide a `formatter` specialization inherited from\n`ostream_formatter`:\n\n #include \n\n struct date {\n int year, month, day;\n\n friend std::ostream& operator<<(std::ostream& os, const date& d) {\n return os << d.year << '-' << d.month << '-' << d.day;\n }\n };\n\n template <> struct fmt::formatter : ostream_formatter {};\n\n std::string s = fmt::format(\"The date is {}\", date{2012, 12, 9});\n // s == \"The date is 2012-12-9\"\n\n::: streamed(const T&)\n\n::: print(std::ostream&, format_string, T&&...)\n\n\n## Dynamic Argument Lists\n\nThe header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API\nthat can be used to construct format argument lists dynamically.\n\n::: dynamic_format_arg_store\n\n\n## Safe `printf`\n\nThe header `fmt/printf.h` provides `printf`-like formatting\nfunctionality. The following functions use [printf format string\nsyntax](https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html)\nwith the POSIX extension for positional arguments. Unlike their standard\ncounterparts, the `fmt` functions are type-safe and throw an exception\nif an argument type doesn't match its format specification.\n\n::: printf(string_view, const T&...)\n\n::: fprintf(std::FILE*, string_view, const T&...)\n\n::: sprintf(string_view, const T&...)\n\n\n## Wide Strings\n\nThe optional header `fmt/xchar.h` provides support for `wchar_t` and\nexotic character types.\n\n::: wstring_view\n\n::: wformat_context\n\n::: to_wstring(const T&)\n\n## Compatibility with C++20 `std::format`\n\n{fmt} implements nearly all of the [C++20 formatting\nlibrary](https://en.cppreference.com/w/cpp/utility/format) with the\nfollowing differences:\n\n- Names are defined in the `fmt` namespace instead of `std` to avoid\n collisions with standard library implementations.\n\n- Width calculation doesn't use grapheme clusterization. The latter has\n been implemented in a separate branch but hasn't been integrated yet.\n\n- The default floating-point representation in {fmt} uses the smallest\n precision that provides round-trip guarantees similarly to other languages\n like Java and Python. `std::format` is currently specified in terms of\n `std::to_chars` which tries to generate the smallest number of characters\n (ignoring redundant digits and sign in exponent) and may produce more\n decimal digits than necessary.\n\n## Configuration Options\n\n{fmt} provides configuration via CMake options and preprocessor macros to\nenable or disable features and to optimize for binary size. For example, you\ncan disable OS-specific APIs defined in `fmt/os.h` with `-DFMT_OS=OFF` when\nconfiguring CMake.\n\n### CMake Options\n\n- **`FMT_OS`**: When set to `OFF`, disables OS-specific APIs (`fmt/os.h`).\n- **`FMT_UNICODE`**: When set to `OFF`, disables Unicode support on\n Windows/MSVC. Unicode support is always enabled on other platforms.\n\n### Macros\n\n- **`FMT_HEADER_ONLY`**: Enables the header-only mode when defined. It is an\n alternative to using the `fmt::fmt-header-only` CMake target.\n Default: not defined.\n\n- **`FMT_USE_EXCEPTIONS`**: Disables the use of exceptions when set to `0`.\n Default: `1` (`0` if compiled with `-fno-exceptions`).\n\n- **`FMT_USE_LOCALE`**: When set to `0`, disables locale support.\n Default: `1` (`0` when `FMT_OPTIMIZE_SIZE > 1`).\n\n- **`FMT_CUSTOM_ASSERT_FAIL`**: When set to `1`, allows users to provide a\n custom `fmt::assert_fail` function which is called on assertion failures and,\n if exceptions are disabled, on runtime errors. Default: `0`.\n\n- **`FMT_BUILTIN_TYPES`**: When set to `0`, disables built-in handling of\n arithmetic and string types other than `int`. This reduces library size at\n the cost of per-call overhead. Default: `1`.\n\n- **`FMT_OPTIMIZE_SIZE`**: Controls binary size optimizations:\n - `0` - off (default)\n - `1` - applies some optimizations\n - `2` - disables locale support by default, some Unicode features, and\n named arguments, and applies more aggressive optimizations\n\n### Binary Size Optimization\n\nTo minimize the binary footprint of {fmt} as much as possible at the cost of\nsome features, you can use the following configuration:\n\n- CMake options:\n - `FMT_OS=OFF`\n- Macros:\n - `FMT_BUILTIN_TYPES=0`\n - `FMT_OPTIMIZE_SIZE=2`\n"}