[#BloombergLP-bdldfp-DecimalUtil-format-00]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdldfp.adoc[bdldfp]::xref:BloombergLP/bdldfp/DecimalUtil.adoc[DecimalUtil]::format
:relfileprefix: ../../../
:mrdocs:

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.

== Synopsis

Declared in `<bdldfp_decimalutil.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
format(
    char* buffer,
    int length,
    xref:BloombergLP/bdldfp/Decimal32.adoc[Decimal32] value,
    xref:BloombergLP/bdldfp/DecimalFormatConfig.adoc[DecimalFormatConfig] const& cfg = DecimalFormatConfig());
----

== Description

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.


[.small]#Created with https://www.mrdocs.com[MrDocs]#