Difference between revisions of "cpp/utility/format/formatted size"
m (Applied P2418 DR.) |
m (Updated formatter requirements.) |
||
Line 26: | Line 26: | ||
Determine the total number of characters in the formatted string by formatting {{tt|args}} according to the format string {{tt|fmt}}. If present, {{tt|loc}} is used for locale-specific formatting. | Determine the total number of characters in the formatted string by formatting {{tt|args}} according to the format string {{tt|fmt}}. If present, {{tt|loc}} is used for locale-specific formatting. | ||
− | The behavior is undefined if {{c|std::formatter<Ti, CharT>}} does not meet the {{named req| | + | The behavior is undefined if {{c|std::formatter<std::remove_cvref_t<Ti>, CharT>}} does not meet the {{named req|BasicFormatter}} requirements for any {{tt|Ti}} in {{tt|Args}}. |
===Parameters=== | ===Parameters=== |
Revision as of 00:25, 16 November 2021
Defined in header <format>
|
||
template< class... Args > std::size_t formatted_size( /*format_string<Args...>*/ fmt, Args&&... args ); |
(1) | (since C++20) |
template< class... Args > std::size_t formatted_size( /*wformat_string<Args...>*/ fmt, Args&&... args ); |
(2) | (since C++20) |
template< class... Args > std::size_t formatted_size( const std::locale& loc, |
(3) | (since C++20) |
template< class... Args > std::size_t formatted_size( const std::locale& loc, |
(4) | (since C++20) |
Determine the total number of characters in the formatted string by formatting args
according to the format string fmt
. If present, loc
is used for locale-specific formatting.
The behavior is undefined if std::formatter<std::remove_cvref_t<Ti>, CharT> does not meet the BasicFormatter requirements for any Ti
in Args
.
Contents |
Parameters
fmt | - | an object that represents the format string. The format string consists of
Each replacement field has the following format:
1) replacement field without a format specification
2) replacement field with a format specification
| ||||||||||||||||||||||||||||||||||||||||||||||
args... | - | arguments to be formatted | ||||||||||||||||||||||||||||||||||||||||||||||
loc | - | std::locale used for locale-specific formatting |
Return value
The total number of characters in the formatted string.
Exceptions
Propagates any exception thrown by formatter.
Example
#include <format> #include <iostream> #include <vector> #include <string_view> int main() { using namespace std::literals::string_view_literals; constexpr auto fmt_str { "Hubble's H{0} {1} {2:*^4} miles/sec/mpc."sv }; constexpr auto sub_zero { "₀"sv }; // { "\u2080"sv } => { 0xe2, 0x82, 0x80 }; constexpr auto aprox_equ { "≅"sv }; // { "\u2245"sv } => { 0xe2, 0x89, 0x85 }; constexpr int Ho { 42 }; // H₀ const auto min_buffer_size = std::formatted_size(fmt_str, sub_zero, aprox_equ, Ho); std::cout << "Min buffer size = " << min_buffer_size << '\n'; // Use std::vector as dynamic buffer. Note: buffer does not include the trailing '\0'. std::vector<char> buffer(min_buffer_size); std::format_to_n(buffer.data(), buffer.size(), fmt_str, sub_zero, aprox_equ, Ho); std::cout << "Buffer: \"" << std::string_view{buffer.data(), min_buffer_size} << "\"\n"; // Or we can print the buffer directly by adding the trailing '\0'. buffer.push_back('\0'); std::cout << "Buffer: \"" << buffer.data() << "\"\n"; }
Output:
Min buffer size = 37 Buffer: "Hubble's H₀ ≅ *42* miles/sec/mpc." Buffer: "Hubble's H₀ ≅ *42* miles/sec/mpc."
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
P2216R3 | C++20 | throws std::format_error for invalid format string | invalid format string results in compile-time error |
P2418R2 | C++20 | objects that are neither const-usable nor copyable (such as generator-like objects) are not formattable |
allow formatting these objects |
See also
(C++20) |
writes out formatted representation of its arguments through an output iterator (function template) |
(C++20) |
writes out formatted representation of its arguments through an output iterator, not exceeding specified size (function template) |