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

Format `value` into `buffer` using `cfg`&period;

== Synopsis

Declared in `&lt;bdldfp&lowbar;decimalimputil&period;h&gt;`

[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

Format the specified `value`, according to the parameters in the specified `cfg`&period; Place the output in the buffer designated by the specified `buffer` and `length`, and return the length of the formatted value&period; 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&period; This function does not write a terminating null character&period; If `length` is not positive, `buffer` is permitted to be null&period; This can be used to determine the necessary buffer size&period; See the  section for information on the configuration attributes&period;

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&period; The number written must be as close as possible to the initial value given the constraints on precision&period; The rounding should be done as &quot;round&hyphen;half&hyphen;up&quot;, i&period;e&period;, round up in magnitude when the first of the discarded digits is between 5 and 9&period;

Also note that if the configuration format attribute `style` is `e&lowbar;NATURAL` then all significand digits of the `value` are output in the buffer regardless of the value specified in configuration&apos;s `precision` attribute&period;

== Return Value

the length of the formatted value

== Parameters

[cols="1,4"]
|===
| Name| Description
| *buffer*
| destination character buffer
| *length*
| capacity of `buffer` in characters
| *value*
| decimal value to format
| *cfg*
| formatting configuration
|===


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