Format value into buffer and return the formatted length.

Synopsis

Declared in <bdldfp_decimalutil.h>

static
int
format(
    char* buffer,
    int length,
    Decimal32 value,
    DecimalFormatConfig const& cfg = DecimalFormatConfig());

Description

Format the specified value, placing the output in the buffer designated by the specified buffer and length, and return the length of the formatted value. If there is insufficient room in the buffer, its contents will be left in an unspecified state, with the returned value indicating the necessary size. This function does not write a terminating null character. If length is not positive, buffer is permitted to be null. This can be used to determine the necessary buffer size. Optionally specify a cfg, indicating formatting parameters. If cfg is not specified, then default configuration instance, indicating scientific notation style with a precision sufficient to produce all available digits is used. See the section for information on the configuration attributes.

Note that for some combinations of value and precision provided by cfg object, the number being written must first be rounded to fewer digits than it initially contains. The number written must be as close as possible to the initial value given the constraints on precision. The rounding should be done as "round‐half‐up", i.e., round up in magnitude when the first of the discarded digits is between 5 and 9.

Also note that if the configuration format attribute style is e_NATURAL then all significand digits of the value are output in the buffer regardless of the value specified in configuration's precision attribute.

Return Value

length of the formatted value

Parameters

Name

Description

buffer

buffer that receives the formatted characters

length

capacity of buffer in bytes

value

decimal value to format

cfg

optional formatting configuration

Created with MrDocs