+
+
+
Safety
+
+ Inspired by Python's formatting facility, {fmt} provides a safe replacement
+ for the printf family of functions. Errors in format strings,
+ which are a common source of vulnerabilities in C, are reported at
+ compile time. For example:
+
+
fmt::format("{:d}", "I am not a number");
+
+ will give a compile-time error because
d is not a valid
+ format specifier for strings. APIs like
+ fmt::format prevent buffer overflow errors via
+ automatic memory management.
+
+
→ Learn more
+
+
+
+
Extensibility
+
+ Formatting of most standard types, including all containers, dates,
+ and times is supported out-of-the-box. For example:
+
+
fmt::print("{}", std::vector{1, 2, 3});
+
+ prints the vector in a JSON-like format:
+
+
[1, 2, 3]
+
+ You can
make your own types formattable and even make compile-time
+ checks work for them.
+
+
→ Learn more
+
+
+
+
Performance
+
+ {fmt} can be anywhere from tens of percent to 20-30 times faster than
+ iostreams and sprintf, especially for numeric formatting.
+
+
+
+
+
+ The library minimizes dynamic memory allocations and can optionally
+ compile format strings to optimal code.
+
+
+
+
+
Unicode support
+
+ {fmt} provides portable Unicode support on major operating systems
+ with UTF-8 and char strings. For example:
+
+
fmt::print("Слава Україні!");
+
+ will be printed correctly on Linux, macOS, and even Windows console,
+ irrespective of the codepages.
+
+
+ The default is locale-independent, but you can opt into localized
+ formatting and {fmt} makes it work with Unicode, addressing issues in the
+ standard libary.
+
+
+
+
+
Fast compilation
+
+ The library makes extensive use of type erasure to achieve fast
+ compilation. fmt/base.h provides a subset of the API with
+ minimal include dependencies and enough functionality to replace
+ all uses of *printf.
+
+
+ Code using {fmt} is usually several times faster to compile than the
+ equivalent iostreams code, and while printf compiles faster
+ still, the gap is narrowing.
+
+
+→ Learn more
+
+
+
+
Small binary footprint
+
+ Type erasure is also used to prevent template bloat, resulting in compact
+ per-call binary code. For example, a call to fmt::print with
+ a single argument is just a few
+ instructions, comparable to printf despite adding
+ runtime safety, and much smaller than the equivalent iostreams code.
+
+
+ The library itself has small binary footprint and some components such as
+ floating-point formatting can be disabled to make it even smaller for
+ resource-constrained devices.
+
+
+
+
+
Portability
+
+ {fmt} has a small self-contained codebase with the core consisting of
+ just three headers and no external dependencies.
+
+
+ The library is highly portable and requires only a minimal subset of
+ C++11 features which are available in GCC 4.8, Clang 3.4, MSVC 19.0
+ (2015) and later. Newer compiler and standard library features are used
+ if available, and enable additional functionality.
+
+
+ Where possible, the output of formatting functions is consistent across
+ platforms.
+
+
+
+
+
+
Open source
+
+ {fmt} is in the top hundred open-source C++ libraries on GitHub and has
+ hundreds of
+ all-time contributors.
+
+
+ The library is distributed under a permissive MIT
+ license and is
+ relied upon by many open-source projects, including Blender, PyTorch,
+ Apple's FoundationDB, Windows Terminal, MongoDB, and others.
+
+
+
+
+
+ | Type |
+ Meaning |
+
+
+ 'a' |
+
+ Hexadecimal floating point format. Prints the number in base 16 with
+ prefix "0x" and lower-case letters for digits above 9.
+ Uses 'p' to indicate the exponent.
+ |
+
+
+ 'A' |
+
+ Same as 'a' except it uses upper-case letters for the
+ prefix, digits above 9 and to indicate the exponent.
+ |
+
+
+ 'e' |
+
+ Exponent notation. Prints the number in scientific notation using
+ the letter 'e' to indicate the exponent.
+ |
+
+
+ 'E' |
+
+ Exponent notation. Same as 'e' except it uses an
+ upper-case 'E' as the separator character.
+ |
+
+
+ 'f' |
+ Fixed point. Displays the number as a fixed-point number. |
+
+
+ 'F' |
+
+ Fixed point. Same as 'f', but converts nan
+ to NAN and inf to INF.
+ |
+
+
+ 'g' |
+
+ General format. For a given precision p >= 1,
+ this rounds the number to p significant digits and then
+ formats the result in either fixed-point format or in scientific
+ notation, depending on its magnitude.
+ A precision of 0 is treated as equivalent to a precision
+ of 1.
+ |
+
+
+ 'G' |
+
+ General format. Same as 'g' except switches to
+ 'E' if the number gets too large. The representations of
+ infinity and NaN are uppercased, too.
+ |
+
+
+ | none |
+
+ Similar to 'g', except that the default precision is as
+ high as needed to represent the particular value.
+ |
+
+
+
+The available presentation types for pointers are:
+
+
+
+ | Type |
+ Meaning |
+
+
+ 'a' |
+
+ The abbreviated weekday name, e.g. "Sat". If the value does not contain a
+ valid weekday, an exception of type format_error is thrown.
+ |
+
+
+ 'A' |
+
+ The full weekday name, e.g. "Saturday". If the value does not contain a
+ valid weekday, an exception of type format_error is thrown.
+ |
+
+
+ 'b' |
+
+ The abbreviated month name, e.g. "Nov". If the value does not contain a
+ valid month, an exception of type format_error is thrown.
+ |
+
+
+ 'B' |
+
+ The full month name, e.g. "November". If the value does not contain a valid
+ month, an exception of type format_error is thrown.
+ |
+
+
+ 'c' |
+
+ The date and time representation, e.g. "Sat Nov 12 22:04:00 1955". The
+ modified command %Ec produces the locale's alternate date and
+ time representation.
+ |
+
+
+ 'C' |
+
+ The year divided by 100 using floored division, e.g. "19". If the result
+ is a single decimal digit, it is prefixed with 0. The modified command
+ %EC produces the locale's alternative representation of the
+ century.
+ |
+
+
+ 'd' |
+
+ The day of month as a decimal number. If the result is a single decimal
+ digit, it is prefixed with 0. The modified command %Od
+ produces the locale's alternative representation.
+ |
+
+
+ 'D' |
+ Equivalent to %m/%d/%y, e.g. "11/12/55". |
+
+
+ 'e' |
+
+ The day of month as a decimal number. If the result is a single decimal
+ digit, it is prefixed with a space. The modified command %Oe
+ produces the locale's alternative representation.
+ |
+
+
+ 'F' |
+ Equivalent to %Y-%m-%d, e.g. "1955-11-12". |
+
+
+ 'g' |
+
+ The last two decimal digits of the ISO week-based year. If the result is a
+ single digit it is prefixed by 0.
+ |
+
+
+ 'G' |
+
+ The ISO week-based year as a decimal number. If the result is less than
+ four digits it is left-padded with 0 to four digits.
+ |
+
+
+ 'h' |
+ Equivalent to %b, e.g. "Nov". |
+
+
+ 'H' |
+
+ The hour (24-hour clock) as a decimal number. If the result is a single
+ digit, it is prefixed with 0. The modified command %OH
+ produces the locale's alternative representation.
+ |
+
+
+ 'I' |
+
+ The hour (12-hour clock) as a decimal number. If the result is a single
+ digit, it is prefixed with 0. The modified command %OI
+ produces the locale's alternative representation.
+ |
+
+
+ 'j' |
+
+ If the type being formatted is a specialization of duration, the decimal
+ number of days without padding. Otherwise, the day of the year as a decimal
+ number. Jan 1 is 001. If the result is less than three digits, it is
+ left-padded with 0 to three digits.
+ |
+
+
+ 'm' |
+
+ The month as a decimal number. Jan is 01. If the result is a single digit,
+ it is prefixed with 0. The modified command %Om produces the
+ locale's alternative representation.
+ |
+
+
+ 'M' |
+
+ The minute as a decimal number. If the result is a single digit, it
+ is prefixed with 0. The modified command %OM produces the
+ locale's alternative representation.
+ |
+
+
+ 'n' |
+ A new-line character. |
+
+
+ 'p' |
+ The AM/PM designations associated with a 12-hour clock. |
+
+
+ 'q' |
+ The duration's unit suffix. |
+
+
+ 'Q' |
+
+ The duration's numeric value (as if extracted via .count()).
+ |
+
+
+ 'r' |
+ The 12-hour clock time, e.g. "10:04:00 PM". |
+
+
+ 'R' |
+ Equivalent to %H:%M, e.g. "22:04". |
+
+
+ 'S' |
+
+ Seconds as a decimal number. If the number of seconds is less than 10, the
+ result is prefixed with 0. If the precision of the input cannot be exactly
+ represented with seconds, then the format is a decimal floating-point number
+ with a fixed format and a precision matching that of the precision of the
+ input (or to a microseconds precision if the conversion to floating-point
+ decimal seconds cannot be made within 18 fractional digits). The character
+ for the decimal point is localized according to the locale. The modified
+ command %OS produces the locale's alternative representation.
+ |
+
+
+ 't' |
+ A horizontal-tab character. |
+
+
+ 'T' |
+ Equivalent to %H:%M:%S. |
+
+
+ 'u' |
+
+ The ISO weekday as a decimal number (1-7), where Monday is 1. The modified
+ command %Ou produces the locale's alternative representation.
+ |
+
+
+ 'U' |
+
+ The week number of the year as a decimal number. The first Sunday of the
+ year is the first day of week 01. Days of the same year prior to that are
+ in week 00. If the result is a single digit, it is prefixed with 0.
+ The modified command %OU produces the locale's alternative
+ representation.
+ |
+
+
+ 'V' |
+
+ The ISO week-based week number as a decimal number. If the result is a
+ single digit, it is prefixed with 0. The modified command %OV
+ produces the locale's alternative representation.
+ |
+
+
+ 'w' |
+
+ The weekday as a decimal number (0-6), where Sunday is 0. The modified
+ command %Ow produces the locale's alternative representation.
+ |
+
+
+ 'W' |
+
+ The week number of the year as a decimal number. The first Monday of the
+ year is the first day of week 01. Days of the same year prior to that are
+ in week 00. If the result is a single digit, it is prefixed with 0.
+ The modified command %OW produces the locale's alternative
+ representation.
+ |
+
+
+ 'x' |
+
+ The date representation, e.g. "11/12/55". The modified command
+ %Ex produces the locale's alternate date representation.
+ |
+
+
+ 'X' |
+
+ The time representation, e.g. "10:04:00". The modified command
+ %EX produces the locale's alternate time representation.
+ |
+
+
+ 'y' |
+
+ The last two decimal digits of the year. If the result is a single digit
+ it is prefixed by 0. The modified command %Oy produces the
+ locale's alternative representation. The modified command %Ey
+ produces the locale's alternative representation of offset from
+ %EC (year only).
+ |
+
+
+ 'Y' |
+
+ The year as a decimal number. If the result is less than four digits it is
+ left-padded with 0 to four digits. The modified command %EY
+ produces the locale's alternative full year representation.
+ |
+
+
+ 'z' |
+
+ The offset from UTC in the ISO 8601:2004 format. For example -0430 refers
+ to 4 hours 30 minutes behind UTC. If the offset is zero, +0000 is used.
+ The modified commands %Ez and %Oz insert a
+ : between the hours and minutes: -04:30. If the offset
+ information is not available, an exception of type
+ format_error is thrown.
+ |
+
+
+ 'Z' |
+
+ The time zone abbreviation. If the time zone abbreviation is not available,
+ an exception of type format_error is thrown.
+ |
+
+
+ '%' |
+ A % character. |
+
+
+
+Specifiers that have a calendaric component such as `'d'` (the day of month)
+are valid only for `std::tm` and time points but not durations.
+
+The available padding modifiers (*padding_modifier*) are:
+
+| Type | Meaning |
+|-------|-----------------------------------------|
+| `'-'` | Pad a numeric result with spaces. |
+| `'_'` | Do not pad a numeric result string. |
+| `'0'` | Pad a numeric result string with zeros. |
+
+These modifiers are only supported for the `'H'`, `'I'`, `'M'`, `'S'`, `'U'`,
+`'V'` and `'W'` presentation types.
+
+## Range Format Specifications
+
+Format specifications for range types have the following syntax:
+
+