Difference between revisions of "cpp/utility/format/basic format parse context"
From cppreference.com
m (fmt) |
(Added LWG 3825.) |
||
| Line 3: | Line 3: | ||
{{dcl begin}} | {{dcl begin}} | ||
| − | {{dcl header | format }} | + | {{dcl header|format}} |
| − | {{dcl | + | {{dcl|since=c++20| |
template< class CharT > | template< class CharT > | ||
class basic_format_parse_context; | class basic_format_parse_context; | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
| Line 18: | Line 12: | ||
Provides access to the format string parsing state consisting of the format string range being parsed and the argument counter for automatic indexing. | Provides access to the format string parsing state consisting of the format string range being parsed and the argument counter for automatic indexing. | ||
| − | A {{tt|basic_format_parse_context}} instance is passed to {{named req|Formatter}} when parsing the format specification. | + | A {{tt|std::basic_format_parse_context}} instance is passed to {{named req|Formatter}} when parsing the format specification. |
| + | |||
| + | {{cpp/basic char typedefs|format_parse_context|format}} | ||
===Member types=== | ===Member types=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc hitem | Type | Definition }} | + | {{dsc hitem|Type|Definition}} |
| − | {{dsc | {{tt|char_type}} | {{tt|CharT}}}} | + | {{dsc|{{tt|char_type}}|{{tt|CharT}}}} |
| − | {{dsc | {{tt|iterator}} | {{c|std::basic_string_view<CharT>::const_iterator}}}} | + | {{dsc|{{tt|iterator}}|{{c/core|std::basic_string_view<CharT>::const_iterator}}}} |
| − | {{dsc | {{tt|const_iterator}} | {{c|std::basic_string_view<CharT>::const_iterator}}}} | + | {{dsc|{{tt|const_iterator}}|{{c/core|std::basic_string_view<CharT>::const_iterator}}}} |
{{dsc end}} | {{dsc end}} | ||
===Member functions=== | ===Member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc mem ctor | nolink=true | constructs a {{tt|std::basic_format_parse_context}} instance from format string and argument count}} | + | {{dsc mem ctor|nolink=true|constructs a {{tt|std::basic_format_parse_context}} instance from format string and argument count}} |
| − | {{dsc mem fun | operator{{=}} | nolink=true | notes={{cmark deleted}} | {{tt|std::basic_format_parse_context}} is not copyable}} | + | {{dsc mem fun|operator{{=}}|nolink=true|notes={{cmark deleted}}|{{tt|std::basic_format_parse_context}} is not copyable}} |
| − | {{dsc mem fun | begin | nolink=true | returns an iterator to the beginning of the format string range}} | + | {{dsc mem fun|begin|nolink=true|returns an iterator to the beginning of the format string range}} |
| − | {{dsc mem fun | end | nolink=true | returns an iterator to the end of the format string range}} | + | {{dsc mem fun|end|nolink=true|returns an iterator to the end of the format string range}} |
| − | {{dsc mem fun | advance_to | nolink=true | advances the begin iterator to the given position}} | + | {{dsc mem fun|advance_to|nolink=true|advances the begin iterator to the given position}} |
| − | {{dsc mem fun | next_arg_id | nolink=true | enters automatic indexing mode, and returns the next argument index}} | + | {{dsc mem fun|next_arg_id|nolink=true|enters automatic indexing mode, and returns the next argument index}} |
| − | {{dsc mem fun | check_arg_id | nolink=true | enters manual indexing mode, checks if the given argument index is in range}} | + | {{dsc mem fun|check_arg_id|nolink=true|enters manual indexing mode, checks if the given argument index is in range}} |
{{dsc end}} | {{dsc end}} | ||
| − | {{member | {{small|std::basic_format_parse_context::}}basic_format_parse_context |2= | + | {{member|{{small|std::basic_format_parse_context::}}basic_format_parse_context|2= |
{{dcl begin}} | {{dcl begin}} | ||
| − | {{dcl | num=1 |1= | + | {{dcl|num=1|1= |
constexpr explicit basic_format_parse_context( std::basic_string_view<CharT> fmt, | constexpr explicit basic_format_parse_context( std::basic_string_view<CharT> fmt, | ||
std::size_t num_args = 0 ) noexcept; | std::size_t num_args = 0 ) noexcept; | ||
}} | }} | ||
| − | {{dcl | num=2 |1= | + | {{dcl|num=2|1= |
basic_format_parse_context(const basic_format_parse_context&) = delete; | basic_format_parse_context(const basic_format_parse_context&) = delete; | ||
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
| − | @1@ Constructs a {{tt|std::basic_format_parse_context}} instance. Initializes the format string range to {{ | + | @1@ Constructs a {{tt|std::basic_format_parse_context}} instance. Initializes the format string range to {{range|fmt.begin()|fmt.end()}}, and the argument count to {{c|num_args}}. |
@2@ The copy constructor is deleted. {{tt|std::basic_format_parse_context}} is not copyable. | @2@ The copy constructor is deleted. {{tt|std::basic_format_parse_context}} is not copyable. | ||
}} | }} | ||
| − | {{member | {{small|std::basic_format_parse_context::}}begin |2= | + | |
| − | {{ddcl | | + | {{member|{{small|std::basic_format_parse_context::}}begin|2= |
| + | {{ddcl| | ||
constexpr const_iterator begin() const noexcept; | constexpr const_iterator begin() const noexcept; | ||
}} | }} | ||
| Line 61: | Line 58: | ||
Returns an iterator to the beginning of the format string range. | Returns an iterator to the beginning of the format string range. | ||
}} | }} | ||
| − | {{member | {{small|std::basic_format_parse_context::}}end |2= | + | |
| − | {{ddcl | | + | {{member|{{small|std::basic_format_parse_context::}}end|2= |
| + | {{ddcl| | ||
constexpr const_iterator end() const noexcept; | constexpr const_iterator end() const noexcept; | ||
}} | }} | ||
| Line 68: | Line 66: | ||
Returns an iterator to the end of the format string range. | Returns an iterator to the end of the format string range. | ||
}} | }} | ||
| − | {{member | {{small|std::basic_format_parse_context::}}advance_to |2= | + | |
| − | {{ddcl | | + | {{member|{{small|std::basic_format_parse_context::}}advance_to|2= |
| + | {{ddcl| | ||
constexpr void advance_to( const_iterator it ); | constexpr void advance_to( const_iterator it ); | ||
}} | }} | ||
| − | Sets the beginning of the format string range to {{ | + | Sets the beginning of the format string range to {{c|it}}. After a call to {{tt|advance_to()}}, subsequent calls to {{tt|begin()}} will return a copy of {{c|it}}. |
| − | The behavior is undefined if {{ | + | The behavior is undefined if {{c|end()}} is not reachable from {{c|it}}. |
}} | }} | ||
| − | {{member | {{small|std::basic_format_parse_context::}}next_arg_id |2= | + | |
| − | {{ddcl | | + | {{member|{{small|std::basic_format_parse_context::}}next_arg_id|2= |
| + | {{ddcl| | ||
constexpr std::size_t next_arg_id(); | constexpr std::size_t next_arg_id(); | ||
}} | }} | ||
| Line 85: | Line 85: | ||
If {{c|*this}} has already entered manual argument indexing mode, throws {{lc|std::format_error}}. | If {{c|*this}} has already entered manual argument indexing mode, throws {{lc|std::format_error}}. | ||
| + | |||
| + | If the next argument index is larger than or equal to the argument count provided in the constructor, the call is not a core constant expression. | ||
}} | }} | ||
| − | {{member | {{small|std::basic_format_parse_context::}}check_arg_id |2= | + | |
| − | {{ddcl | | + | {{member|{{small|std::basic_format_parse_context::}}check_arg_id|2= |
| + | {{ddcl| | ||
constexpr void check_arg_id( std::size_t id ); | constexpr void check_arg_id( std::size_t id ); | ||
}} | }} | ||
| Line 95: | Line 98: | ||
If {{c|*this}} has already entered automatic argument indexing mode, throws {{lc|std::format_error}}. | If {{c|*this}} has already entered automatic argument indexing mode, throws {{lc|std::format_error}}. | ||
| − | If {{ | + | If {{c|id}} is larger than or equal to the number of arguments provided in the constructor, the call is not a core constant expression. |
}} | }} | ||
===Example=== | ===Example=== | ||
{{example | {{example | ||
| − | + | |code= | |
| − | + | |output= | |
}} | }} | ||
| − | === | + | ===Defect reports=== |
| + | {{dr list begin}} | ||
| + | {{dr list item|wg=lwg|dr=3825|std=C++20|before={{tt|check_arg_id}} has a compile-time argument<br>{{c|id}} check, but {{tt|next_arg_id}} did not have|after=added}} | ||
| + | {{dr list end}} | ||
{{langlinks|es|ja|zh}} | {{langlinks|es|ja|zh}} | ||
Revision as of 19:10, 5 April 2023
| Defined in header <format>
|
||
| template< class CharT > class basic_format_parse_context; |
(since C++20) | |
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.
Several typedefs for common character types are provided:
| Defined in header
<format> | |
| Type | Definition |
std::format_parse_context
|
std::basic_format_parse_context<char> |
std::wformat_parse_context
|
std::basic_format_parse_context<wchar_t> |
Member types
| Type | Definition |
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) |
std::basic_format_parse_context::basic_format_parse_context
| constexpr explicit basic_format_parse_context( std::basic_string_view<CharT> fmt, std::size_t num_args = 0 ) noexcept; |
(1) | |
| basic_format_parse_context(const basic_format_parse_context&) = delete; |
(2) | |
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.2) The copy constructor is deleted.
std::basic_format_parse_context is not copyable.
std::basic_format_parse_context::begin
| constexpr const_iterator begin() const noexcept; |
||
Returns an iterator to the beginning of the format string range.
std::basic_format_parse_context::end
| constexpr const_iterator end() const noexcept; |
||
Returns an iterator to the end of the format string range.
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.
The behavior is undefined if end() is not reachable from it.
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, throws std::format_error.
If the next argument index is larger than or equal to the argument count 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, throws std::format_error.
If id is larger than or equal to the number of arguments provided in the constructor, the call is not a core constant expression.
Example
| This section is incomplete Reason: no example |
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3825 | C++20 | check_arg_id has a compile-time argumentid check, but next_arg_id did not have
|
added |
