标准库标头 <format> (C++20)

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

功能特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

标准库头

语言支持 <cfloat> <climits> <compare> (C++20) <contracts> (C++26) <coroutine> (C++20) <csetjmp> <csignal> <cstdarg> <cstddef> <cstdint> (C++11) <cstdlib> <exception> <initializer_list> (C++11)    <limits> <new> <source_location> (C++20) <stdfloat> (C++23) <typeinfo> <version> (C++20) 概念 <concepts> (C++20) 诊断 <cassert> <cerrno> <debugging> (C++26) <stacktrace> (C++23) <stdexcept> <system_error> (C++11) 内存管理 <memory> <memory_resource> (C++17) <scoped_allocator> (C++11) 元编程 <type_traits> (C++11) <ratio> (C++11)

通用工具 <any> (C++17) <bitset> <bit> (C++20) <charconv> (C++17) <expected> (C++23) <format> (C++20) <functional> <optional> (C++17) <stdbit.h> (C++26) <tuple> (C++11) <typeindex> (C++11) <utility> <variant> (C++17) 容器 <array> (C++11) <deque> <flat_map> (C++23) <flat_set> (C++23) <forward_list> (C++11) <hive> (C++26) <inplace_vector> (C++26)    <list> <map> <mdspan> (C++23) <queue> <set> <span> (C++20) <stack> <unordered_map> (C++11) <unordered_set> (C++11) <vector> 迭代器 <iterator> 范围 <generator> (C++23) <ranges> (C++20)

算法 <algorithm> <numeric> 字符串 <cctype> <cstring> <cuchar> (C++11) <cwchar> <cwctype> <string_view> (C++17) <string> 文本处理 <clocale> <codecvt> (C++11/17/26*) <locale> <regex> (C++11) <text_encoding> (C++26)    cpp/header#数值库数值 <cfenv> (C++11) <cmath> <complex> <linalg> (C++26) <numbers> (C++20) <random> (C++11) <simd> (C++26) <stdckdint.h> (C++26) <valarray> 时间 <chrono> (C++11) <ctime> C 兼容性 <ccomplex> (C++11/17/20*) <ciso646> (C++20 前) <cstdalign> (C++11/17/20*) <cstdbool> (C++11/17/20*) <ctgmath> (C++11/17/20*)

输入/输出 <cinttypes> (C++11) <cstdio> <filesystem> (C++17) <fstream> <iomanip> <iosfwd> <iostream> <ios> <istream> <ostream> <print> (C++23) <spanstream> (C++23) <sstream> <streambuf> <strstream> (C++98/26*) <syncstream> (C++20) 并发支持 <atomic> (C++11) <barrier> (C++20) <condition_variable> (C++11) <future> (C++11) <hazard_pointer> (C++26) <latch> (C++20) <mutex> (C++11) <rcu> (C++26) <semaphore> (C++20) <shared_mutex> (C++14) <stdatomic.h> (C++23) <stop_token> (C++20) <thread> (C++11) 执行支持 <execution> (C++17)

 

此标头是文本处理库的一部分。

概念
formattable (C++23)	指示一个类型可格式化，即它特化了 std::formatter 并且提供了成员函数 parse 和 format (概念)
枚举
range_format (C++23)	指示一个范围应该如何被格式化 (枚举)
类
formatter (C++20)	定义针对给定类型的格式化规则 (类模板)
range_formatter (C++23)	用于帮助实现 std::formatter 对范围类型的特化的类模板 (类模板)
basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)	格式化字符串分析器状态 (类模板)
basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	格式化状态，包括所有格式化参数和输出迭代器 (类模板)
basic_format_arg (C++20)	提供对用户定义格式化器的格式化参数的访问的类模板 (类模板)
basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)	提供对所有格式化参数的访问的类 (类模板)
basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)	在构造时执行编译期格式字符串检查的类模板 (类模板)
format_error (C++20)	格式化错误时抛出的异常类型 (类)
格式化器的特化
std::formatter<pair 或 tuple> (C++23)	pair 和 tuple 的格式化支持 (类模板特化)
std::formatter<范围> (C++23)	范围的格式化支持 (类模板特化)
函数
format (C++20)	在新字符串中存储参数的格式化表示 (函数模板)
format_to (C++20)	通过输出迭代器写入其实参的格式化表示 (函数模板)
format_to_n (C++20)	通过输出迭代器写入其实参的格式化表示，不超出指定的大小 (函数模板)
formatted_size (C++20)	确定存储其参数的格式化表示所需的字符数 (函数模板)
runtime_format (C++26)	创建能直接用于面向用户的格式化函数的运行时格式串 (函数)
vformat (C++20)	std::format 的使用类型擦除的参数表示的非模板变体 (函数)
vformat_to (C++20)	std::format_to 的使用类型擦除的参数表示的非模板变体 (函数模板)
visit_format_arg (C++20) (C++26 弃用)	用户定义格式化器的参数探访接口 (函数模板)
make_format_argsmake_wformat_args (C++20)(C++20)	创建引用所有格式化参数的类型擦除对象，可转换到 format_args (函数模板)
辅助类型
format_kind (C++23)	为范围选择合适的 std::range_format (变量模板)
enable_nonlocking_formatter_optimization (C++23)	指示实现可以高效打印实参类型 (变量模板)

概要

namespace std {
  // 类模板 basic_format_context
  template<class Out, class CharT> class basic_format_context;
  using format_context = basic_format_context</* 未指定 */, char>;
  using wformat_context = basic_format_context</* 未指定 */, wchar_t>;
 
  // 类模板 basic_format_args
  template<class Context> class basic_format_args;
  using format_args = basic_format_args<format_context>;
  using wformat_args = basic_format_args<wformat_context>;
 
  // 类模板 basic_format_string
  template<class CharT, class... Args> struct basic_format_string;
 
  template<class CharT> struct /*runtime-format-string*/
  {                                   // 仅用于阐释
  private:
    basic_string_view<CharT> /*str*/; // 仅用于阐释
  public:
    /*runtime-format-string*/(basic_string_view<CharT> s) noexcept
      : /*str*/(s)
    {
    }
    /*runtime-format-string*/(const /*runtime-format-string*/&) = delete;
    /*runtime-format-string*/& operator=(const /*runtime-format-string*/&) = delete;
  };
  /*runtime-format-string*/<char> runtime_format(string_view fmt) noexcept { return fmt; }
  /*runtime-format-string*/<wchar_t> runtime_format(wstring_view fmt) noexcept
  {
    return fmt;
  }
 
  template<class... Args>
  using format_string = basic_format_string<char, type_identity_t<Args>...>;
  template<class... Args>
  using wformat_string = basic_format_string<wchar_t, type_identity_t<Args>...>;
 
  // 格式化函数
  template<class... Args> string format(format_string<Args...> fmt, Args&&... args);
  template<class... Args> wstring format(wformat_string<Args...> fmt, Args&&... args);
  template<class... Args>
  string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class... Args>
  wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
 
  string vformat(string_view fmt, format_args args);
  wstring vformat(wstring_view fmt, wformat_args args);
  string vformat(const locale& loc, string_view fmt, format_args args);
  wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
 
  template<class Out, class... Args>
  Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
  Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
  Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
  Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
 
  template<class Out> Out vformat_to(Out out, string_view fmt, format_args args);
  template<class Out> Out vformat_to(Out out, wstring_view fmt, wformat_args args);
  template<class Out>
  Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
  template<class Out>
  Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
 
  template<class Out> struct format_to_n_result
  {
    Out out;
    iter_difference_t<Out> size;
  };
  template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out,
                                      iter_difference_t<Out> n,
                                      format_string<Args...> fmt,
                                      Args&&... args);
  template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out,
                                      iter_difference_t<Out> n,
                                      wformat_string<Args...> fmt,
                                      Args&&... args);
  template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out,
                                      iter_difference_t<Out> n,
                                      const locale& loc,
                                      format_string<Args...> fmt,
                                      Args&&... args);
  template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out,
                                      iter_difference_t<Out> n,
                                      const locale& loc,
                                      wformat_string<Args...> fmt,
                                      Args&&... args);
 
  template<class... Args>
  size_t formatted_size(format_string<Args...> fmt, Args&&... args);
  template<class... Args>
  size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
  template<class... Args>
  size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class... Args>
  size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
 
  // 格式化器
  template<class T, class CharT = char>
    struct formatter;
 
  // 格式化器的锁定
   template<class T> constexpr bool enable_nonlocking_formatter_optimization = false;
 
  // 概念 formattable
  template<class T, class CharT>
  concept formattable = /* 见描述 */;
 
  template<class R, class CharT>
  concept /*const-formattable-range*/ = // 仅用于阐释
    ranges::input_range<const R> &&
    formattable<ranges::range_reference_t<const R>, CharT>;
 
  template<class R, class CharT>
  using /*fmt-maybe-const*/ =           // 仅用于阐释
    conditional_t</*const-formattable-range*/<R, CharT>, const R, R>;
 
  // 类模板 basic_format_parse_context
  template<class CharT> class basic_format_parse_context;
  using format_parse_context = basic_format_parse_context<char>;
  using wformat_parse_context = basic_format_parse_context<wchar_t>;
 
  // 范围格式化
  // 变量模板 format_kind
  enum class range_format
  {
    disabled,
    map,
    set,
    sequence,
    string,
    debug_string
  };
 
  template<class R> constexpr /* unspecified */ format_kind = /* unspecified */;
 
  template<ranges::input_range R>
    requires same_as<R, remove_cvref_t<R>>
  constexpr range_format format_kind<R> = /* 见描述 */;
 
  // 类模板 range_formatter
  template<class T, class CharT = char>
    requires same_as<remove_cvref_t<T>, T> && formattable<T, CharT>
  class range_formatter;
 
  // 类模板 range-default-formatter
  template<range_format K, ranges::input_range R, class CharT>
  struct /*range-default-formatter*/; // 仅用于阐释
 
  // 针对映射、集合和字符串的特化
  template<ranges::input_range R, class CharT>
     requires(format_kind<R> != range_format::disabled) &&
              formattable<ranges::range_reference_t<R>, CharT>
  struct formatter<R, CharT> : /*range-default-formatter*/<format_kind<R>, R, CharT>
  {};
 
  template<ranges::input_range R>
    requires(format_kind<R> != range_format::disabled)
  constexpr bool enable_nonlocking_formatter_optimization<R> = false;
 
  // 实参
  // 类模板 basic_format_arg
  template<class Context> class basic_format_arg;
 
  // 类模板 format-arg-store
  template<class Context, class... Args> class /*format-arg-store*/; // 仅用于阐释
 
  template<class Context = format_context, class... Args>
  /*format-arg-store*/<Context, Args...> make_format_args(Args&... fmt_args);
  template<class... Args>
  /*format-arg-store*/<wformat_context, Args...> make_wformat_args(Args&... args);
 
  // 类 format_error
  class format_error;
}

类模板 std::basic_format_string

namespace std {
  template<class CharT, class... Args> struct basic_format_string
  {
  private:
    basic_string_view<CharT> /*str*/; // 仅用于阐释
 
  public:
    template<class T> consteval basic_format_string(const T& s);
    basic_format_string(/*runtime-format-string*/<CharT> s) noexcept
      : str(s./*str*/)
    {
    }
    constexpr basic_string_view<CharT> get() const noexcept { return /*str*/; }
  };
}

概念 std::formattable

template<class T, class CharT>
  concept formattable =
    semiregular<formatter<remove_cvref_t<T>, CharT>> &&
    requires(formatter<remove_cvref_t<T>, CharT> f,
             const formatter<remove_cvref_t<T>, CharT> cf,
             T t,
             basic_format_context<__fmt_iter_for<CharT>, CharT> fc,
             basic_format_parse_context<CharT> pc) {
        { f.parse(pc) } -> same_as<basic_format_parse_context<CharT>::iterator>;
        { cf.format(t, fc) } -> same_as<__fmt_iter_for<CharT>>;
    };

类模板 std::basic_format_parse_context

namespace std {
  template<class charT> class basic_format_parse_context
  {
  public:
    using char_type = charT;
    using const_iterator = typename basic_string_view<charT>::const_iterator;
    using iterator = const_iterator;
 
  private:
    iterator begin_;     // 仅用于阐述
    iterator end_;       // 仅用于阐述
    enum indexing
    {
      unknown,
      manual,
      automatic
    };                   // 仅用于阐述
    indexing indexing_;  // 仅用于阐述
    size_t next_arg_id_; // 仅用于阐述
    size_t num_args_;    // 仅用于阐述
 
  public:
    constexpr explicit basic_format_parse_context(basic_string_view<CharT> fmt) noexcept;
    basic_format_parse_context(const basic_format_parse_context&) = delete;
    basic_format_parse_context& operator=(const basic_format_parse_context&) = delete;
 
    constexpr const_iterator begin() const noexcept;
    constexpr const_iterator end() const noexcept;
    constexpr void advance_to(const_iterator it);
 
    constexpr size_t next_arg_id();
    constexpr void check_arg_id(size_t id);
 
    template<class... Ts> constexpr void check_dynamic_spec(size_t id) noexcept;
    constexpr void check_dynamic_spec_integral(size_t id) noexcept;
    constexpr void check_dynamic_spec_string(size_t id) noexcept;
  };
}

类模板 std::basic_format_context

namespace std {
  template<class Out, class charT> class basic_format_context
  {
    basic_format_args<basic_format_context> args_; // 仅用于阐述
    Out out_;                                      // 仅用于阐述
 
    basic_format_context(const basic_format_context&) = delete;
    basic_format_context& operator=(const basic_format_context&) = delete;
 
  public:
    using iterator = Out;
    using char_type = CharT;
    template<class T> using formatter_type = formatter<T, CharT>;
 
    basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
    std::locale locale();
 
    iterator out();
    void advance_to(iterator it);
  };
}

变量模板 std::format_kind

template<ranges::input_range R>
  requires same_as<R, remove_cvref_t<R>>
constexpr range_format format_kind<R> = /* 见描述 */;

类模板 std::range_formatter

namespace std {
  template<class T, class CharT = char>
    requires same_as<remove_cvref_t<T>, T> && formattable<T, CharT>
  class range_formatter
  {
    formatter<T, CharT> /*underlying_*/; // 仅用于阐释
    basic_string_view<CharT> /*separator_*/ =
      /*STATICALLY-WIDEN*/<CharT>(", "); // 仅用于阐释
    basic_string_view<CharT> /*opening-bracket_*/ =
      /*STATICALLY-WIDEN*/<CharT>("[");  // 仅用于阐释
    basic_string_view<CharT> /*closing-bracket_*/ =
      /*STATICALLY-WIDEN*/<CharT>("]");  // 仅用于阐释
 
  public:
    constexpr void set_separator(basic_string_view<CharT> sep) noexcept;
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing) noexcept;
    constexpr formatter<T, CharT>& underlying() noexcept { return /*underlying_*/; }
    constexpr const formatter<T, CharT>& underlying() const noexcept
    {
      return /*underlying_*/;
    }
 
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
 
    template<ranges::input_range R, class FormatContext>
      requires formattable<ranges::range_reference_t<R>, CharT> &&
               same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
    typename FormatContext::iterator format(R&& r, FormatContext& ctx) const;
  };
}

类模板 __range_default_formatter

namespace std {
  template<ranges::input_range R, class CharT>
  struct /*range-default-formatter*/<range_format::sequence, R, CharT>
  {                                                          // 仅用于阐释
  private:
    using /*maybe-const-r*/ = /*fmt-maybe-const*/<R, CharT>; // 仅用于阐释
    range_formatter<remove_cvref_t<ranges::range_reference_t</*maybe-const-r*/>>,
                    CharT>
      /*underlying_*/;                                       // 仅用于阐释
 
  public:
    constexpr void set_separator(basic_string_view<CharT> sep) noexcept;
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing) noexcept;
 
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
 
    template<class FormatContext>
    typename FormatContext::iterator format(/*maybe-const-r*/& elems,
                                            FormatContext& ctx) const;
  };
}

__range_default_formatter 针对映射的特化

namespace std {
  template<ranges::input_range R, class CharT>
  struct /*range-default-formatter*/<range_format::map, R, CharT>
  {
  private:
    using /*maybe-const-map*/ = /*fmt-maybe-const*/<R, CharT>; // 仅用于阐释
    using /*element-type*/ =                                   // 仅用于阐释
      remove_cvref_t<ranges::range_reference_t</*maybe-const-map*/>>;
    range_formatter</*element-type*/, CharT> /*underlying_*/;  // 仅用于阐释
 
  public:
    constexpr /*range-default-formatter*/();
 
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
 
    template<class FormatContext>
    typename FormatContext::iterator format(/*maybe-const-map*/& r,
                                            FormatContext& ctx) const;
  };
}

__range_default_formatter 针对集合的特化

namespace std {
  template<ranges::input_range R, class CharT>
  struct /*range-default-formatter*/<range_format::set, R, CharT>
  {
  private:
    using /*maybe-const-set*/ = /*fmt-maybe-const*/<R, CharT>; // 仅用于阐释
    range_formatter<remove_cvref_t<ranges::range_reference_t</*maybe-const-set*/>>,
                    CharT>
      /*underlying_*/;                                         // 仅用于阐释
 
  public:
    constexpr /*range-default-formatter*/();
 
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
 
    template<class FormatContext>
    typename FormatContext::iterator format(/*maybe-const-set*/& r,
                                            FormatContext& ctx) const;
  };
}

__range_default_formatter 针对字符串的特化

namespace std {
  template<range_format K, ranges::input_range R, class CharT>
    requires(K == range_format::string || K == range_format::debug_string)
  struct /*range-default-formatter*/<K, R, CharT>
  {
  private:
    formatter<basic_string<CharT>, CharT> /*underlying_*/; // 仅用于阐释
 
  public:
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
 
    template<class FormatContext>
    typename FormatContext::iterator format(/* 见描述 */ &str,
                                            FormatContext& ctx) const;
  };
}

类模板 std::basic_format_arg

namespace std {
  template<class Context> class basic_format_arg
  {
  public:
    class handle;
 
  private:
    using char_type = typename Context::char_type; // 仅用于阐释
 
    variant<monostate,
            bool,
            char_type,
            int,
            unsigned int,
            long long int,
            unsigned long long int,
            float,
            double,
            long double,
            const char_type*,
            basic_string_view<char_type>,
            const void*,
            handle>
      value;                                                    // 仅用于阐释
 
    template<class T> explicit basic_format_arg(T& v) noexcept; // 仅用于阐释
 
  public:
    basic_format_arg() noexcept;
 
    explicit operator bool() const noexcept;
 
    template<class Visitor>
    decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);
    template<class R, class Visitor> R visit(this basic_format_arg arg, Visitor&& vis);
  };
}

类 std::basic_format_arg::handle

namespace std {
  template<class Context> class basic_format_arg<Context>::handle
  {
    const void* ptr_;                                   // 仅用于阐述
    void (*format_)(basic_format_parse_context<char_type>&,
                    Context&,
                    const void*);                       // 仅用于阐述
 
    template<class T> explicit handle(T& val) noexcept; // 仅用于阐述
 
  public:
    void format(basic_format_parse_context<char_type>&, Context& ctx) const;
  };
}

类模板 format-arg-store

namespace std {
  template<class Context, class... Args> class /*format-arg-store*/
  {                                                             // 仅用于阐述
    array<basic_format_arg<Context>, sizeof...(Args)> /*args*/; // 仅用于阐述
  };
}

类模板 std::basic_format_args

namespace std {
  template<class Context> class basic_format_args
  {
    size_t size_;                           // 仅用于阐述
    const basic_format_arg<Context>* data_; // 仅用于阐述
 
  public:
    template<class... Args>
    basic_format_args(const /*format-arg-store*/<Context, Args...>& store) noexcept;
 
    basic_format_arg<Context> get(size_t i) const noexcept;
  };
 
  template<class Context, class... Args>
  basic_format_args(/*format-arg-store*/<Context, Args...>) -> basic_format_args<Context>;
}

元组格式化器

namespace std {
  template<class CharT, formattable<CharT>... Ts>
  struct formatter</*pair-or-tuple*/<Ts...>, CharT>
  {
  private:
    tuple<formatter<remove_cvref_t<Ts>, CharT>...> /*underlying_*/; // 仅用于阐述
    basic_string_view<CharT> /*separator_*/ =
      /*STATICALLY-WIDEN*/<CharT>(", ");                            // 仅用于阐述
    basic_string_view<CharT> /*opening-bracket_*/ =
      /*STATICALLY-WIDEN*/<CharT>("(");                             // 仅用于阐述
    basic_string_view<CharT> /*closing-bracket_*/ =
      /*STATICALLY-WIDEN*/<CharT>(")");                             // 仅用于阐述
 
  public:
    constexpr void set_separator(basic_string_view<CharT> sep) noexcept;
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing) noexcept;
 
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
 
    template<class FormatContext>
    typename FormatContext::iterator format(/* 见描述 */ &elems,
                                            FormatContext& ctx) const;
  };
 
  template<class... Ts>
  constexpr bool enable_nonlocking_formatter_optimization</*pair-or-tuple*/<Ts...>> =
    (enable_nonlocking_formatter_optimization<Ts> && ...);
}

类 std::format_error

namespace std {
  class format_error : public runtime_error
  {
  public:
    constexpr explicit format_error(const string& what_arg);
    constexpr explicit format_error(const char* what_arg);
  };
}