{"id":5998,"date":"2020-10-11T08:57:08","date_gmt":"2020-10-11T08:57:08","guid":{"rendered":"https:\/\/www.modernescpp.com\/index.php\/extend-std-format-in-c-20-for-user-defined-types\/"},"modified":"2023-06-26T09:42:13","modified_gmt":"2023-06-26T09:42:13","slug":"extend-std-format-in-c-20-for-user-defined-types","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/extend-std-format-in-c-20-for-user-defined-types\/","title":{"rendered":"C++20: Extend std::format for User-Defined Types"},"content":{"rendered":"

Peter Gottschling presented in his last post “std::format in C++20<\/a>” the basics of the new formatting library in C++20. In today’s post, Peter writes about the formatting of user-defined types.<\/p>\n

<\/p>\n

 \"TimelineCpp20CoreLanguage\"<\/p>\n

Our first example of template specialization is customizing the new format library introduced to support user types.<\/p>\n

Formatting User-Defined Types<\/h2>\n

For example, we choose the dmc::vector<\/code> (dmc<\/code> is the namespace from the book “Discovering Modern C++” by the author) class for which we like to specify the formatting of the single values. In addition, we want to replace the enclosing brackets with curly braces when the format string contains the letter 'c'<\/code>. To this end, we have to specialize the class std::formatter <\/code><\/a>(or fmt::formatter<\/code> for the prototype library fmt<\/a><\/code>). Our specialization shall contain the methods parse<\/code> and format<\/code>.<\/p>\n

Let’s start with the former:<\/p>\n

<\/p>\n

\n
template<\/span> <<\/span>typename<\/span> Value><\/span>\r\nstruct<\/span> formatter<<\/span>dmc::<\/span>vector<<\/span>Value>><\/span>\r\n{\r\n    constexpr auto<\/span> parse(format_parse_context&<\/span> ctx)\r\n    {\r\n        value_format=<\/span> \"{:\"<\/span>;        \r\n        for<\/span> (auto<\/span> it=<\/span> begin(ctx); it !=<\/span> end(ctx); ++<\/span>it) {\r\n            char<\/span> c=<\/span> *<\/span>it;\r\n            if<\/span> (c ==<\/span> 'c'<\/span>)\r\n                curly=<\/span> true<\/span>;\r\n            else<\/span>\r\n                value_format+=<\/span> c;\r\n            if<\/span> (c ==<\/span> '}'<\/span>)\r\n                return<\/span> it;\r\n        }\r\n        return<\/span> end(ctx);\r\n    }\r\n    \/\/ ...<\/span>\r\n    bool<\/span>        curly{false<\/span>};\r\n    std::<\/span>string value_format;\r\n};\r\n<\/pre>\n<\/div>\n
 <\/p>\n
As an argument, the parse context is given whose begin<\/code> iterator points to the first character of the format specification, i.e.~the first character after the colon and, in its absence, the first character after the opening brace. We copy the format specification almost identically to our local value_format,<\/code> only our unique character 'c'<\/code> is skipped. For simplicity, we assume that the format doesn’t contain any opening or closing brace, so the next closing brace terminates our format string. Finally, we return the iterator pointing to the closing brace or the end iterator.<\/p>\n
With this information, we can output our <\/span><\/span>vector<\/code> in the method <\/span><\/span>format<\/code>:<\/span><\/span><\/p>\n
<\/p>\n
\n
template<\/span> <<\/span>typename<\/span> Value><\/span>\r\nstruct<\/span> formatter<<\/span>dmc::<\/span>vector<<\/span>Value>><\/span>\r\n{\r\n    template<\/span> <<\/span>typename<\/span> FormatContext><\/span>\r\n    auto<\/span> format(const<\/span> dmc::<\/span>vector<<\/span>Value>&<\/span> v, FormatContext&<\/span> ctx)\r\n    {\r\n        auto<\/span>&&<\/span> out=<\/span> ctx.out();\r\n        format_to(out, curly ?<\/span> \"{{\"<\/span> :<\/span> \"[\"<\/span>);\r\n        if<\/span> (v.size() ><\/span> 0<\/span>)\r\n            format_to(out, value_format, v[0<\/span>]);\r\n        for<\/span> (int<\/span> i=<\/span> 1<\/span>; i <<\/span> v.size(); ++<\/span>i)\r\n            format_to(out, \", \"<\/span> +<\/span> value_format, v[i]);\r\n        return<\/span> format_to<\/span>(out, curly ?<\/span> \"}}\"<\/span> :<\/span> \"]\"<\/span>);\r\n    }\r\n    \/\/ ...<\/span>\r\n};\r\n<\/pre>\n<\/div>\n
 <\/p>\n
First, we take a reference to the output buffer. Then we write the opening brace or bracket to it. Since braces have a special meaning in the format<\/code> library, we need an escape sequence of double braces. The remaining output is equivalent to the ostream<\/code> output. Finally, we return the output buffer.<\/p>\n
Now we can try various formats:<\/span><\/p>\n
<\/p>\n
\n
dmc::<\/span>vector<<\/span>double<\/span>><\/span> v{1.394<\/span>, 1e9<\/span>, 1.0<\/span>\/<\/span>3.0<\/span>, 1e-20<\/span>};\r\nprint(\"v with empty format = {:}.<\/span>\\n<\/span>\"<\/span>, v);\r\nprint(\"v with f = {:f}.<\/span>\\n<\/span>\"<\/span>, v);\r\nprint(\"v curly with f = {:fc}.<\/span>\\n<\/span>\"<\/span>, v);\r\nprint(\"v width 9, 4 digits = {:9.4f}.<\/span>\\n<\/span>\"<\/span>, v);\r\nprint(\"v scient. = {:ec}.<\/span>\\n<\/span>\"<\/span>, v);\r\n<\/pre>\n<\/div>\n
 <\/p>\n
and see the outputs:<\/p>\n
<\/p>\n
\n
v with empty format = [1.394, 1000000000.0, 0.3333333333333333, 1e-20].\r\nv with f = [1.394000, 1000000000.000000, 0.333333, 0.000000].\r\nv curly with f = {1.394000, 1000000000.000000, 0.333333, 0.000000}.\r\nv width 9, 4 digits = [   1.3940, 1000000000.0000,    0.3333,    0.0000].\r\nv scient. = {1.394000e+00, 1.000000e+09, 3.333333e-01, 1.000000e-20}.\r\n<\/pre>\n<\/div>\n
 <\/p>\n
Altogether, since the new formatting is:<\/p>\n