std::basic_...arse_context(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

💖 std::basic_...arse_context(3) 💖

okay bestie, this is the std::basic_format_parse_context(3) page from the C++ Standard Libary manual (yes, that spelling is right up there 😭). Buckle up, we're getting into format-string parsing state and it's honestly kind of iconic.

🌸 NAME 🌸

std::basic_format_parse_context — std::basic_format_parse_context

(the name says it twice and honestly? slay.)

✨ Synopsis ✨

Defined in header <format>:

Defined in header <format>
template< class CharT >            (since C++20)
class basic_format_parse_context;

Provides access to the format string parsing state consisting of the format string range being parsed and the argument counter for automatic indexing.

A std::basic_format_parse_context instance is passed to Formatter when parsing the format specification.

🚨 Important bestie warning: a program that declares an explicit or partial specialization of std::basic_format_parse_context is ill-formed, no diagnostic required. Not a vibe. Do not do it. 🙈

Several typedefs for common character types are provided:

Defined in header <format>:

  • std::format_parse_context — std::basic_format_parse_context<char>
  • std::wformat_parse_context — std::basic_format_parse_context<wchar_t>

🧚 Member types 🧚

  • char_type — CharT
  • iterator — std::basic_string_view<CharT>::const_iterator
  • const_iterator — std::basic_string_view<CharT>::const_iterator

🛠️ Member functions 🛠️

  • constructor — constructs a std::basic_format_parse_context instance from format string and argument count (public member function)
  • operator= [deleted] — std::basic_format_parse_context is not copyable (public member function)
  • begin — returns an iterator to the beginning of the format string range (public member function)
  • end — returns an iterator to the end of the format string range (public member function)
  • advance_to — advances the begin iterator to the given position (public member function)
  • next_arg_id — enters automatic indexing mode, and returns the next argument index (public member function)
  • check_arg_id — enters manual indexing mode, checks if the given argument index is in range (public member function)
  • check_dynamic_spec (C++26) — checks if the type of the corresponding format argument with the given argument index is in the given type template arguments (public member function)
  • check_dynamic_spec_integral (C++26) — checks if the type of the corresponding format argument with the given argument index is an integral type (public member function)
  • check_dynamic_spec_string (C++26) — checks if the type of the corresponding format argument with the given argument index is a string type (public member function)

🌈 std::basic_format_parse_context::basic_format_parse_context 🌈

constexpr explicit
basic_format_parse_context( std::basic_string_view<CharT> fmt,   (until C++26)
                            std::size_t num_args = 0 )
noexcept;                                                      (1)
constexpr explicit
basic_format_parse_context( std::basic_string_view<CharT> fmt   (since C++26)
) noexcept;
basic_format_parse_context( const basic_format_parse_context&   (2)
) = delete;
  1. Constructs a std::basic_format_parse_context instance. Initializes the format string range to [fmt.begin(), fmt.end()), and the argument count to num_args (until C++26) or 0 (since C++26). Any call to next_arg_id, check_arg_id, or check_dynamic_spec on an instance of std::basic_format_parse_context initialized using this constructor is not a core constant expression. (the since C++26 energy is floating around this one, iykyk)
  2. The copy constructor is deleted. std::basic_format_parse_context is not copyable. no cap.

🦋 std::basic_format_parse_context::begin 🦋

constexpr const_iterator begin() const noexcept;

Returns an iterator to the beginning of the format string range. It's giving start-of-the-range realness ✨

🎀 std::basic_format_parse_context::end 🎀

constexpr const_iterator end() const noexcept;

Returns an iterator to the end of the format string range. The finish line of the format string range, periodt.

💅 std::basic_format_parse_context::advance_to 💅

constexpr void advance_to( const_iterator it );

Sets the beginning of the format string range to it. After a call to advance_to(), subsequent calls to begin() will return a copy of it.

💀 Behavior is undefined if end() is not reachable from it. So please don't be messy with this one, bestie. That's a real undefined-behavior jump scare.

🔥 std::basic_format_parse_context::next_arg_id 🔥

constexpr std::size_t next_arg_id();

Enters automatic argument indexing mode, and returns the next argument index, starting from 0.

If *this has already entered manual argument indexing mode, it throws std::format_error.

If the next argument index is larger than or equal to the num_args provided in the constructor, the call is not a core constant expression.

⭐ std::basic_format_parse_context::check_arg_id ⭐

constexpr void check_arg_id( std::size_t id );

Enters manual argument indexing mode.

If *this has already entered automatic argument indexing mode, it throws std::format_error.

If id is larger than or equal to the num_args provided in the constructor, the call is not a core constant expression.

🌸 std::basic_format_parse_context::check_dynamic_spec 🌸

template< class... Ts >                                        (since C++26)
constexpr void check_dynamic_spec( std::size_t id ) noexcept;

If id is larger than or equal to the num_args provided in the constructor or the type of the corresponding format argument (after conversion to std::basic_format_arg) is not one of the types in Ts..., the call is not a core constant expression. A call to check_dynamic_spec has no effect at runtime.

  • This overload participates in overload resolution only if the types in Ts... are unique and each type is one of bool, char_type, int, unsigned int, long long int, unsigned long long int, float, double, long double, const char_type*, std::basic_string_view<char_type>, or const void*.

🫶 std::basic_format_parse_context::check_dynamic_spec_integral 🫶

constexpr void check_dynamic_spec_integral( std::size_t id ) (since C++26)
noexcept;

Equivalent to call check_dynamic_spec<int, unsigned int, long long int, unsigned long long int>(id). A call to check_dynamic_spec_integral has no effect at runtime.

🍓 std::basic_format_parse_context::check_dynamic_spec_string 🍓

constexpr void check_dynamic_spec_string( std::size_t id ) noexcept; (since C++26)

Equivalent to call check_dynamic_spec<const char_type*, std::basic_string_view<char_type>>(id). A call to check_dynamic_spec_string has no effect at runtime.

🧸 Example 🧸

This section is incomplete. Reason: no example 😭

👑 Defect reports 👑

The following behavior-changing defect reports were applied retroactively to previously published C++ standards:

  • LWG 3825 — applied to C++20. Behavior as published: check_arg_id has a compile-time argument id check, but next_arg_id did not have. Correct behavior: added.
  • LWG 3975 — applied to C++20. Behavior as published: user specialization of basic_format_parse_context was allowed. Correct behavior: disallowed.

🏷️ Category 🏷️

  • Todo no example

source: http://cppreference.com · version/date: 2024.06.10 · page: std::basic_...arse_context(3) — mwah, bye bestie 💅🫶

📦 where this page comes from