{"id":5996,"date":"2020-10-02T05:47:01","date_gmt":"2020-10-02T05:47:01","guid":{"rendered":"https:\/\/www.modernescpp.com\/index.php\/std-format-in-c-20\/"},"modified":"2023-06-26T09:42:32","modified_gmt":"2023-06-26T09:42:32","slug":"std-format-in-c-20","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/std-format-in-c-20\/","title":{"rendered":"std::format in C++20"},"content":{"rendered":"

Today, I’m happy to present Peter Gottschling’s guest post to the new formatting library in C++20: std::format<\/code>.  Thanks to std::format<\/code>, text formatting becomes in C++20 as easy as in Python.<\/p>\n

<\/p>\n

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

Peter is the author of the must-read book “Discovering Modern C++<\/a>”  for professional C++ developers.<\/p>\n

New Formatting<\/h2>\n

Traditional stream formatting requires a fair amount of typing. Format strings in printf<\/code> and alike are more expressive and allow us to declare with few symbols what we’ve written with multiple I\/O manipulators. <\/p>\n

Nonetheless, we advise against using printf<\/code>. For two reasons, it can’t be used with user types and is not type-safe. The format string is parsed at run time, and the following arguments are treated with an obscure macro mechanism. If the arguments don’t match the format string, the behavior is undefined and can cause program crashes. For instance, a string is passed as a pointer, and from the pointed address on, the bytes are read and printed as char<\/code> until a binary 0<\/code> is found in memory. If we accidentally try printing an int<\/code> as a string, the int<\/code> value is misinterpreted as an address from which a sequence  char<\/code> shall be printed. This will result in either absolute nonsensical output or (more likely) a memory error if the address is inaccessible. We must admit that recent compilers parse format strings (when known at compile time) and warn about argument mismatches.<\/p>\n

The new format <\/a>library {By the time of writing, no compiler supported the library, and the examples were implemented with its prototype version: the fmt <\/a>library. The format library combines the expressibility of the format string with the type safety and the user-extensibility of stream I\/O. It adds the opportunity to reorder the arguments in the output.<\/p>\n

Integrals<\/h3>\n

Instead of a formal specification, we port some printf<\/code> examples from cppreference.com<\/a> to the new format:<\/p>\n

<\/p>\n

\n
print(\"Decimal:<\/span>\\t<\/span>{} {} {:06} {} {:0} {:+} {:d}<\/span>\\n<\/span>\"<\/span>, 1<\/span>, 2<\/span>, 3<\/span>, 0<\/span>, 0<\/span>, 4<\/span>, -<\/span>1<\/span>);\r\n\r\nprint(\"Hexadecimal:<\/span>\\t<\/span>{:x} {:x} {:X} {:#x}<\/span>\\n<\/span>\"<\/span>, 5<\/span>, 10<\/span>, 10<\/span>, 6<\/span>);\r\n\r\nprint(\"Octal:<\/span>\\t\\t<\/span>{:o} {:#o} {:#o}<\/span>\\n<\/span>\"<\/span>, 10<\/span>, 10<\/span>, 4<\/span>);\r\n\r\nprint(\"Binary:<\/span>\\t\\t<\/span>{:b} {:#b} {:#b}<\/span>\\n<\/span>\"<\/span>, 10<\/span>, 10<\/span>, 4<\/span>);\r\n<\/pre>\n<\/div>\n
 <\/p>\n
This snippet prints:<\/p>\n
<\/p>\n
\n
Decimal:        1 2 000003 0 0 +4 -1\r\n\r\nHexadecimal:    5 a A 0x6\r\n\r\nOctal:          12 012 04\r\n\r\nBinary:         1010 0b1010 0b100
\r\n<\/pre>\n<\/div>\n
The first two numbers were just printed without giving any format information. The exact output is generated when we ask for a decimal number with the format specifier :d. <\/code>The third number shall be printed (minimally) 6~characters wide and filled with 0<\/code>s. The specifier +<\/code> allows us to force printing the sign for all numbers. printf<\/code> allows for specifying unsigned<\/code> the output of numbers. That leads to incorrect large numbers when the value to print is negative. The format<\/code> library refrains from user declarations of  unsigned <\/code>output since this information is already contained in the type of the according to the argument. If somebody wants to print a negative value as a largely positive, he must convert it explicitly.<\/p>\n
The second line demonstrates that we can print values hexadecimally with the lower and upper case for digits larger than 9. The specifier #<\/code> generates the prefix 0x<\/code> used in hexadecimal literals.<\/p>\n
Likewise, we can print the values as octal and binaries, optionally with the according to literal prefix.<\/p>\n<\/p>\n
Floating-Point Numbers<\/h3>\n
With floating-point numbers, we have more formatting options:<\/p>\n
<\/p>\n
\n
print(\"Default:<\/span>\\t<\/span>{} {:g} {:g}<\/span>\\n<\/span>\"<\/span>, 1.5<\/span>, 1.5<\/span>, 1e20<\/span>);\r\n\r\nprint(\"Rounding:<\/span>\\t<\/span>{:f} {:.0f} {:.22f}<\/span>\\n<\/span>\"<\/span>, 1.5<\/span>, 1.5<\/span>, 1.3<\/span>);\r\n\r\nprint(\"Padding:<\/span>\\t<\/span>{:05.2f} {:.2f} {:5.2f}<\/span>\\n<\/span>\"<\/span>, 1.5<\/span>, 1.5<\/span>, 1.5<\/span>);\r\n\r\nprint(\"Scientific:<\/span>\\t<\/span>{:E} {:e}<\/span>\\n<\/span>\"<\/span>, 1.5<\/span>, 1.5<\/span>);\r\n\r\nprint(\"Hexadecimal:<\/span>\\t<\/span>{:a} {:A}<\/span>\\n\\n<\/span>\"<\/span>, 1.5<\/span>, 1.3<\/span>);\r\n<\/pre>\n<\/div>\n
 <\/p>\n
Then we get:<\/p>\n
<\/p>\n
\n
Default:        1.5 1.5 1e+20\r\n\r\nRounding:       1.500000 2 1.3000000000000000444089\r\n\r\nPadding:        01.50 1.50  1.50\r\n\r\nScientific:     1.500000E+00 1.500000e+00\r\n\r\nHexadecimal:    0x1.8p+0 0X1.4CCCCCCCCCCCDP+0\r\n<\/pre>\n<\/div>\n
 <\/p>\n
We get the default output with empty braces or only containing a colon. This corresponds to the format specifier :g<\/code> and yields the same output as streams without the manipulators. The number of fractional digits can be given between a dot and the format specifier f<\/code>. Then the value is rounded to that precision. If the requested number is larger than what is representable by the value’s type, the last digits aren’t significant. A digit in front of the dot specifies the (minimal) width of the output. As with integers, we can request leading 0<\/code>s. Floating-point numbers can be printed in scientific notation with either upper or lower case e<\/code> to start the exponential part. The hexadecimal output can initialize a variable in another program with precisely the same bits.<\/p>\n
Redirecting Output<\/h3>\n
The output can be redirected to any other std::ostream (<\/code>Requires including ostream.h<\/code> with the fmt library.):<\/p>\n
<\/p>\n
\n
print(std::<\/span>cerr, \"System error code = {}<\/span>\\n<\/span>\"<\/span>, 7<\/span>);\r\n\r\nofstream error_file<\/span>(\"error_file.txt\"<\/span>);\r\n\r\nprint(error_file, \"System error code = {}<\/span>\\n<\/span>\"<\/span>, 7<\/span>);<\/pre>\n<\/div>\n
Reordering Arguments and Name them<\/h3>\n
In contrast to printf<\/code>, arguments can now be reordered:<\/p>\n
<\/p>\n
\n
print(\"I'd rather be {1} than {0}.<\/span>\\n<\/span>\"<\/span>, \"right\"<\/span>, \"happy\"<\/span>);\r\n<\/pre>\n<\/div>\n
 <\/p>\n
In addition to referring to the arguments by their positions, we can give them names:<\/p>\n
<\/p>\n
\n
print(\"Hello, {name}! The answer is {number}. Goodbye, {name}.<\/span>\\n<\/span>\"<\/span>,\r\n      arg(\"name\"<\/span>, name), arg(\"number\"<\/span>, number));\r\n<\/pre>\n<\/div>\n
 <\/p>\n
Or, more concisely:<\/p>\n
<\/p>\n
\n
print(\"Hello, {name}! The answer is {number}. Goodbye, {name}.<\/span>\\n<\/span>\"<\/span>,\r\n      \"name\"<\/span>_a=<\/span>name, \"number\"<\/span>_a=<\/span>number);\r\n<\/pre>\n<\/div>\n
 <\/p>\n