[#BloombergLP-bdldfp-DecimalImpUtil-format-0e]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdldfp.adoc[bdldfp]::xref:BloombergLP/bdldfp/DecimalImpUtil.adoc[DecimalImpUtil]::format
:relfileprefix: ../../../
:mrdocs:

Format the specified `value`, according to the parameters in the specified `cfg`. Place 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. See the  section for information on the configuration attributes.

== Synopsis

Declared in `<bdldfp_decimalimputil.h>`

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

== 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]#