标准库标头 <format>

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

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

语言支持库

概念库 (C++20)

元编程库 (C++11)

诊断库

通用工具库

字符串库

容器库

迭代器库

范围库 (C++20)

算法库

数值库

本地化库

输入/输出库

文件系统库 (C++17)

正则表达式库 (C++11)

并发支持库 (C++11)

技术规范

符号索引

外部库

 

标准库标头

注：修订记号中的反斜杠 '/' 意味着此标头被弃用和/或被移除。

语言支持
<cstddef> <cstdlib> <version> (C++20) <limits> <climits>	<cfloat> <cstdint> (C++11) <stdfloat> (C++23) <new> <typeinfo>	<source_location> (C++20) <exception> <initializer_list> (C++11) <compare> (C++20)	<coroutine> (C++20) <csignal> <csetjmp> <cstdarg>
概念
<concepts> (C++20)
诊断
<stdexcept> <stacktrace> (C++23)	<cassert>	<cerrno>	<system_error> (C++11)
内存管理
<memory>	<memory_resource> (C++17)	<scoped_allocator> (C++11)
元编程
<type_traits> (C++11)	<ratio> (C++11)
通用工具
<utility> <tuple> (C++11) <optional> (C++17) <variant> (C++17)	<any> (C++17) <expected> (C++23) <bitset>	<functional> <typeindex> (C++11) <execution> (C++17)	<charconv> (C++17) <format> (C++20) <bit> (C++20)
字符串
<string_view> (C++17) <string>	<cctype> <cwctype>	<cstring> <cwchar>	<cuchar> (C++11)
容器
<array> (C++11) <deque> <forward_list> (C++11) <list>	<vector> <map> <set> <unordered_map> (C++11)	<unordered_set> (C++11) <queue> <stack> <flat_map> (C++23)	<flat_set> (C++23) <span> (C++20) <mdspan> (C++23)
迭代器
<iterator>
范围
<ranges> (C++20)	<generator> (C++23)
算法
<algorithm>	<execution>
数值
<cfenv> (C++11) <complex>	<random> (C++11) <valarray>	<cmath>	<numbers> (C++20)
日期时间
<chrono> (C++11)	<ctime>
本地化
<locale>	<clocale>	<codecvt> (C++11/17)
输入/输出
<iosfwd> <iostream> <ios> <streambuf>	<istream> <ostream> <iomanip> <print> (C++23)	<sstream> <spanstream> (C++23) <fstream> <syncstream> (C++20)	<filesystem> (C++17) <cstdio> <cinttypes> (C++11) <strstream> (C++98/)
正则表达式
<regex>
并发支持
<stop_token> (C++20) <thread> (C++11) <atomic> (C++11)	<stdatomic.h> (C++23) <mutex> (C++11) <shared_mutex> (C++14)	<condition_variable> (C++11)   <semaphore> (C++20) <latch> (C++20)	<barrier> (C++20) <future> (C++11)
C 兼容
<cstdbool> (C++11/17/20)   <ccomplex> (C++11/17/20)	<ctgmath> (C++11/17/20)	<cstdalign> (C++11/17/20)	<ciso646> (C++20 前)

 

此头文件是格式化库的一部分。

类
formatter (C++20)	定义给定类型的格式化规则的类模板 (类模板)
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)	提供对所有格式化参数的访问的类 (类模板)
format_error (C++20)	格式化错误时抛出的异常类型 (类)
函数
format (C++20)	在新 string 中存储参数的格式化表示 (函数模板)
format_to (C++20)	通过输出迭代器写其参数的格式化表示 (函数模板)
format_to_n (C++20)	通过输出迭代器写其参数的格式化表示，不超出指定的大小 (函数模板)
formatted_size (C++20)	确定存储其参数的格式化表示所需的字符数 (函数模板)
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 (函数模板)

概要

namespace std {
  // 格式化函数
  template<class... Args>
    string format(string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(wstring_view fmt, const Args&... args);
  template<class... Args>
    string format(const locale& loc, string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(const locale& loc, wstring_view fmt, const 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, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, wstring_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
 
  template<class Out>
    Out vformat_to(Out out, string_view fmt,
                   format_args_t<type_identity_t<Out>, char> args);
  template<class Out>
    Out vformat_to(Out out, wstring_view fmt,
                   format_args_t<type_identity_t<Out>, wchar_t> args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, string_view fmt,
                   format_args_t<type_identity_t<Out>, char> args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                   format_args_t<type_identity_t<Out>, wchar_t> 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,
                                        string_view fmt, const Args&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        wstring_view fmt, const 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, string_view fmt,
                                        const 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, wstring_view fmt,
                                        const Args&... args);
 
  template<class... Args>
    size_t formatted_size(string_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(wstring_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
 
  // 格式化器
  template<class T, class charT = char> struct formatter;
 
  // 类模板 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>;
 
  template<class Out, class charT> class basic_format_context;
  using format_context = basic_format_context<unspecified, char>;
  using wformat_context = basic_format_context<unspecified, wchar_t>;
 
  // 实参
  // 类模板 basic_format_arg
  template<class Context> class basic_format_arg;
 
  template<class Visitor, class Context>
    /* 见描述 */ visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
 
  // class template format-arg-store
  template<class Context, class... Args> struct /*format-arg-store*/;  // 仅为阐释
 
  template<class Context = format_context, class... Args>
    /*format-arg-store*/<Context, Args...>
      make_format_args(const Args&... args);
  template<class... Args>
    /*format-arg-store*/<wformat_context, Args...>
      make_wformat_args(const Args&... args);
 
  // 类模板 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>;
 
  template<class Out, class charT>
    using format_args_t = basic_format_args<basic_format_context<Out, charT>>;
 
  // 类 format_error
  class format_error;
}

类模板 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,
                                                  size_t num_args = 0) 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);
  };
}

类模板 std::basic_format_context

namespace std {
  template<class Out, class charT>
  class basic_format_context {
    basic_format_args<basic_format_context> args_;      // 仅为阐释
    Out out_;                                           // 仅为阐释
 
  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;
    std::locale locale();
 
    iterator out();
    void advance_to(iterator it);
  };
}

类模板 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(const T& v) noexcept;  // 仅为阐释
    explicit basic_format_arg(float n) noexcept;                       // 仅为阐释
    explicit basic_format_arg(double n) noexcept;                      // 仅为阐释
    explicit basic_format_arg(long double n) noexcept;                 // 仅为阐释
    explicit basic_format_arg(const char_type* s);                     // 仅为阐释
 
    template<class traits>
      explicit basic_format_arg(
        basic_string_view<char_type, traits> s) noexcept;              // 仅为阐释
 
    template<class traits, class Allocator>
      explicit basic_format_arg(
        const basic_string<char_type, traits, Allocator>& s) noexcept; // 仅为阐释
 
    explicit basic_format_arg(nullptr_t) noexcept;                     // 仅为阐释
 
    template<class T>
      explicit basic_format_arg(const T* p) noexcept;                  // 仅为阐释
 
  public:
    basic_format_arg() noexcept;
 
    explicit operator bool() const noexcept;
  };
}

类 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(const T& val) noexcept;   // 仅为阐释
 
    friend class basic_format_arg<Context>;                     // 仅为阐释
 
  public:
    void format(basic_format_parse_context<char_type>&, Context& ctx) const;
  };
}

类模板 format-arg-store

namespace std {
  template<class Context, class... Args>
  struct /*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:
    basic_format_args() noexcept;
 
    template<class... Args>
      basic_format_args(const /*format-arg-store*/<Context, Args...>& store) noexcept;
 
    basic_format_arg<Context> get(size_t i) const noexcept;
  };
}

类 std::format_error

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