Lines Matching +full:code +full:- +full:format +full:- +full:checks
1 .. _string-formatting-api:
9 * :ref:`fmt/core.h <core-api>`: the core API providing main formatting functions
10 for ``char``/UTF-8 with C++20 compile-time checks and minimal dependencies
11 * :ref:`fmt/format.h <format-api>`: the full format API providing additional
13 * :ref:`fmt/ranges.h <ranges-api>`: formatting of ranges and tuples
14 * :ref:`fmt/chrono.h <chrono-api>`: date and time formatting
15 * :ref:`fmt/std.h <std-api>`: formatters for standard library types
16 * :ref:`fmt/compile.h <compile-api>`: format string compilation
17 * :ref:`fmt/color.h <color-api>`: terminal color and text style
18 * :ref:`fmt/os.h <os-api>`: system APIs
19 * :ref:`fmt/ostream.h <ostream-api>`: ``std::ostream`` support
20 * :ref:`fmt/args.h <args-api>`: dynamic argument lists
21 * :ref:`fmt/printf.h <printf-api>`: ``printf`` formatting
22 * :ref:`fmt/xchar.h <xchar-api>`: optional ``wchar_t`` support
27 .. _core-api:
33 for ``char``/UTF-8 with C++20 compile-time checks. It has minimal include
35 using {fmt} as a library (the default) and not in the header-only mode.
36 It also provides ``formatter`` specializations for built-in and string types.
38 The following functions use :ref:`format string syntax <syntax>`
39 similar to that of Python's `str.format
40 <https://docs.python.org/3/library/stdtypes.html#str.format>`_.
43 *fmt* is a format string that contains literal text and replacement fields
45 in the resulting string. `~fmt::format_string` is a format string which can be
47 checked at compile time in C++20. To pass a runtime format string wrap it in
58 .. doxygenfunction:: format(format_string<T...> fmt, T&&... args) -> std::string
59 .. doxygenfunction:: vformat(string_view fmt, format_args args) -> std::string
61 .. doxygenfunction:: format_to(OutputIt out, format_string<T...> fmt, T&&... args) -> OutputIt
62 .. doxygenfunction:: format_to_n(OutputIt out, size_t n, format_string<T...> fmt, T&&... args) -> f…
63 .. doxygenfunction:: formatted_size(format_string<T...> fmt, T&&... args) -> size_t
76 Compile-Time Format String Checks
77 ---------------------------------
79 Compile-time format string checks are enabled by default on compilers
81 :ref:`FMT_STRING <legacy-checks>`: macro defined in ``fmt/format.h`` instead.
83 Unused arguments are allowed as in Python's `str.format` and ordinary functions.
90 .. doxygenfunction:: fmt::runtime(string_view) -> runtime_format_string<>
94 Formatting User-Defined Types
95 -----------------------------
98 See :ref:`fmt/ranges.h <ranges-api>` for ranges and tuples including standard
99 containers such as ``std::vector``, :ref:`fmt/chrono.h <chrono-api>` for date
100 and time formatting and :ref:`fmt/std.h <std-api>` for other standard library
103 There are two ways to make a user-defined type formattable: providing a
107 with the same format specifiers. The ``format_as`` function should take an
113 #include <fmt/format.h>
128 your type and implement ``parse`` and ``format`` methods.
131 inheritance or composition. This way you can support standard format specifiers
142 auto format(color c, format_context& ctx) const;
147 #include <fmt/format.h>
149 auto fmt::formatter<color>::format(color c, format_context& ctx) const {
156 return formatter<string_view>::format(name, ctx);
159 Note that ``formatter<string_view>::format`` is defined in ``fmt/format.h`` so
161 ``formatter<string_view>`` it will recognize all string format specifications,
164 .. code-block:: c++
166 fmt::format("{:>10}", color::blue)
175 #include <fmt/format.h>
183 auto format(point p, format_context& ctx) const {
204 // Parses format specifiers and stores them in the formatter.
207 // contains a part of the format string starting from the format
210 // fmt::format("{:f} continued", ...);
217 -> format_parse_context::iterator;
219 // Formats value using the parsed format specification stored in this
221 auto format(const T& value, format_context& ctx) const
222 -> format_context::iterator;
246 auto format(const A& a, format_context& ctx) const {
247 return fmt::formatter<std::string>::format(a.name(), ctx);
253 #include <fmt/format.h>
265 ---------------
269 Named arguments are not supported in compile-time checks at the moment.
272 --------------
274 You can create your own formatting function with compile-time checks and small
277 .. code:: c++
281 void vlog(const char* file, int line, fmt::string_view format,
284 fmt::vprint(format, args);
288 void log(const char* file, int line, fmt::format_string<T...> format, T&&... args) {
289 vlog(file, line, format, fmt::make_format_args(args...));
292 #define MY_LOG(format, ...) log(__FILE__, __LINE__, format, __VA_ARGS__)
297 times and reduces binary code size compared to a fully parameterized version.
320 .. _args-api:
323 ----------------------
325 The header ``fmt/args.h`` provides ``dynamic_format_arg_store``, a builder-like
326 API that can be used to construct format argument lists dynamically.
332 -------------
339 .. _format-api:
341 Format API
344 ``fmt/format.h`` defines the full format API providing additional formatting
347 Literal-Based API
348 -----------------
350 The following user-defined literals are defined in ``fmt/format.h``.
355 ---------
357 .. doxygenfunction:: fmt::ptr(T p) -> const void*
358 .. doxygenfunction:: fmt::ptr(const std::unique_ptr<T, Deleter> &p) -> const void*
359 .. doxygenfunction:: fmt::ptr(const std::shared_ptr<T> &p) -> const void*
361 .. doxygenfunction:: fmt::underlying(Enum e) -> typename std::underlying_type<Enum>::type
363 .. doxygenfunction:: fmt::to_string(const T &value) -> std::string
365 .. doxygenfunction:: fmt::join(Range &&range, string_view sep) -> join_view<detail::iterator_t<Rang…
367 .. doxygenfunction:: fmt::join(It begin, Sentinel end, string_view sep) -> join_view<It, Sentinel>
369 .. doxygenfunction:: fmt::group_digits(T value) -> group_digits_view<T>
375 :protected-members:
379 -------------
390 -----------------
413 inline custom_string format(custom_allocator alloc,
420 normally don't do any allocations for built-in and string types except for
421 non-default floating-point formatting that occasionally falls back on
425 ------
427 All formatting is locale-independent by default. Use the ``'L'`` format
434 std::locale::global(std::locale("en_US.UTF-8"));
435 auto s = fmt::format("{:L}", 1000000); // s == "1,000,000"
437 ``fmt/format.h`` provides the following overloads of formatting functions that
441 .. doxygenfunction:: format(const Locale& loc, format_string<T...> fmt, T&&... args) -> std::string
442 …tion:: format_to(OutputIt out, const Locale& loc, format_string<T...> fmt, T&&... args) -> OutputIt
443 .. doxygenfunction:: formatted_size(const Locale& loc, format_string<T...> fmt, T&&... args) -> siz…
445 .. _legacy-checks:
447 Legacy Compile-Time Format String Checks
448 ----------------------------------------
450 ``FMT_STRING`` enables compile-time checks on older compilers. It requires C++14
451 or later and is a no-op in C++11.
455 To force the use of legacy compile-time checks, define the preprocessor variable
459 .. _ranges-api:
474 ``format.h`` header, but expect this to change in the future.
484 .. _chrono-api:
496 The format syntax is described in :ref:`chrono-specs`.
505 // Prints "The date is 2020-11-07." (with the current date):
506 fmt::print("The date is {:%Y-%m-%d}.", fmt::localtime(t));
510 // Prints "Default format: 42s 100ms":
511 fmt::print("Default format: {} {}\n", 42s, 100ms);
513 // Prints "strftime-like format: 03:15:30":
514 fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
521 .. _std-api:
535 -------------------
551 .. _compile-api:
553 Format String Compilation
556 ``fmt/compile.h`` provides format string compilation enabled via the
557 ``FMT_COMPILE`` macro or the ``_cf`` user-defined literal. Format strings
559 efficient formatting code at compile-time. This supports arguments of built-in
560 and string types as well as user-defined types with ``format`` functions taking
561 the format context type as a template parameter in their ``formatter``
568 auto format(const point& p, FormatContext& ctx) const;
571 Format string compilation can generate more binary code compared to the default
579 .. _color-api:
594 .. _os-api:
604 .. _ostream-api:
610 user-defined types that have an overloaded insertion operator (``operator<<``).
620 return os << d.year << '-' << d.month << '-' << d.day;
626 std::string s = fmt::format("The date is {}", date{2012, 12, 9});
627 // s == "The date is 2012-12-9"
633 .. _printf-api:
638 The header ``fmt/printf.h`` provides ``printf``-like formatting functionality.
639 The following functions use `printf format string syntax
642 counterparts, the ``fmt`` functions are type-safe and throw an exception if an
643 argument type doesn't match its format specification.
645 .. doxygenfunction:: printf(string_view fmt, const T&... args) -> int
647 .. doxygenfunction:: fprintf(std::FILE *f, const S &fmt, const T&... args) -> int
651 .. _xchar-api:
667 Compatibility with C++20 ``std::format``
671 <https://en.cppreference.com/w/cpp/utility/format>`_ with the following