- Generated by
1.9.8
|
BDE 4.39.x Production Release
|
Provide documentation for bsl::format of bdlt value types.
Provide documentation for bsl::format of bdlt value types
This component provides documentation and a usage example demonstrating the behavior and features of bsl::format as applied to bdlt value types.
@SEE ALSO: bdlt_dateformatter, bdlt_datetzformatter, bdlt_timeformatter, bdlt_timetzformatter, bdlt_datetimeformatter, bdlt_datetimetzformatter
bsl::format is a powerful formatting function that can be used to format, among other things, bdlt value types. The formatting of types is controlled by a set of formatting options that are specified in the format string passed to bsl::format in a way very similar to how the format string in printf formats types being printed. While printf can only format a few hard-coded types, bsl::format can be extended to format more sophisticated types, and all bdlt value types are supported with such extensions.
The format string passed to bsl::format can contain any number of % sequences, which are replaced by the formatted value of the corresponding argument, or part of the corresponding argument. Each type has a specific, limited set of %-sequences that can be used with it, and using any other %-sequence is an error. The formatting options for bdlt value types are described both in this component and in the component documentation of each bdlt value type.
The following is a list of %-sequences supported for bdlt value types, though not all the sequences are supported for all the types. Many of the sequences are copied from std::formats support for std::chrono::duration, see https://en.cppreference.com/w/cpp/chrono/duration.html, but some other ones are specific to bdlt value types.
Just like for all other bsl::format errors, errors will be detected at compile time in C++20 and later, but in C++17 and earlier, errors will result in an exception being thrown at run time.
Literal % sequences that just output one fixed character are:
"%%" - outputs ("%")"%n" - outputs newline ("\n")"%t" - outputs tab ("\t")All % sequences supported for bdlt value types are:
"%D" same as "{:%d%h%Y}""%F" Iso8601, like "{:%Y-%m-%d}""%T", same as "{:%H:%M:%S}", 6 digit fraction"%z", 2 digit hour and 2-digit minute offset from UTC, with or without a colon separating hours and minutes"%Y" (4-digit), "%y" (2-digit)"%C" (2-digit)"%m" (2-digit)"%b" or "%h""%d" (0-padded), "%e" (space-padded)"%a" (3 letter upper case)"%u" (numeric 1-7, Monday is 1)"%w" (numeric 0-6, Sunday is 0)"%j" (numeric 3-digit)"%H" (2 digit) 00 - 24"%I" (2 digit) 01 - 12"%p" - AM or PM"%M" (2 digits) 00 - 59"%S" (2 digits 00 - 59 + . + fraction)"{}" formats the value as if streamed by <<, default 6 digit precision for seconds, no : between hours and minutes of any time zone"%i" for bdlt value types formats the entire value like Iso8601, were precision defaults to 3 digit and there's a : between hours and minutes of any time zone.It is an error to specify a %-sequence that does not apply to the type being formatted, or a sub-type of it – for example, all sequences that apply to Date or Time can be used on a Datetime object.
bsl::format strings of bdlt value types take the form of either "{}" or "{:[padding][precision][bdlt-modifiers]["%"-sequences]}" where all fields surrounded by "[]"s are optional. While in printf the modifiers of a %-sequence occur between the % and the type specifier, in bsl::format the modifiers occur between the first : and the first % (if any).
padding takes the form of <pad character><alignment command><width> where<pad character> is the character to pad with, which defaults to space if omitted, and must be a single character<alignment command> is one of: < for left, > for right, and ^ for centered, and<width> is the minimum total width of the padded value outputprecision is indicated by a . followed by an integral number of digits.bdlt-modifiers are specific to bdlt value types. One affects the output of seconds, and three affect the output of time zones:, decimal between integral seconds and fraction is a comma instead of a period: separate hours and minutes in time zone with :_ suppress : between hours and minutes in time zoneZ if time zone offset is 0, display it as Z Characters after the first % that are not part of a valid %-sequence are copied to output without modification. The modifiers must come in the order "<padding><precision><bdlt-specific modifiers>". The bdlt-specific modifiers must come last, but among themselves, may occur in any order.First, include the files necessary to declare the bdlt value types that we will use and their formatters:
Next, create a form of assertion macro that will compare a literal string to the result of an expression and output the value of the expression if they don't match (continuations elided in .h to suppress compiler errors):
Declare a few variables of bdlt value types:
The simplest way to format a bdlt type using bsl::format is to use the "{}" format string. In this case, bsl::format will produce the same output as streaming that value into a bsl::ostream. If more control is required, we can use %-sequences to select which parts of the value are formatted, in which order, and to add any text to separate them.
A Time can also be formatted with "%T":
A Date can be formatted with "%D":
The format function can print multiple variables in a single call:
In bdlt formatting, any %-sequence that works on a type also works on other types that contain that type, and time zones can be formatted as "%z".
%-sequences can appear any number of times:
After the first : and before the first %, if any, one can indicate padding with "<pad char><alignment char><width>" where:
< for left, > for right, ^ for centered After the padding specification (if any) and before the first % (if any), one can indicate the precision, the number of digits of fractional seconds. This is specified as a period followed by a non-negative integral number of digits to occur after the decimal. If the precision is 0, no decimal will be shown:
After the padding and/or precision specifiers (if any), when formatting bdlt types, one can provide modifiers that change the behavior of the correlating %-sequences. Currently, there is one modifier that affects the formatting of fractional seconds and three modifiers that affect time zone formatting:
, the decimal in seconds is to be a comma rather than a period: always separate time zone hours and minutes by colon_ never separate time zone hours and minutes by colonZ if the time zone offset is zero, print it as Z, otherwise, the Z modifier is ignoredErrors in the format string such as:
%-sequence that is not supported for that type: and the first %-sequence that are not part of a valid padding specification, precision, or bdlt-modifier will cause a compilation error in C++20 or later, or cause a bsl::format_error exception to be thrown at runtime in C++17 or earlier.Padding width and precision can be passed through the argument list at run time:
"%i" - format the whole value according to the same format as bdlt::Iso8601::generate. Iso8601 formatting differs from formatting the value with the "{}" format string in several ways:
: between hours and minutes, rather than no separatorDates are done in the format "YYYY-MM-DD" rather than "DDMMMYYYY", so that when sorted, they will sort chronologicallyDatetime are separated by T rather than _"%i"-sequences are supported for all bdlt value types:
The _ bdlt-modifier can be used to suppress the colon in the time zone:
bsl::format does not support showing names or abbreviations of time zones, they are always listed as numerical hours & minutes.
Using various %-sequences, one can arrange different pieces of the value in any desired order. For example, it is possible to replicate the "%i" format using other sequences:
Other %-sequences can be used to arrange the value in other ways, or to achieve specific output formats. For example:
1.9.8