[#BloombergLP-bdlde-CharConvertUtf32-utf32ToUtf8-05]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlde.adoc[bdlde]::xref:BloombergLP/bdlde/CharConvertUtf32.adoc[CharConvertUtf32]::utf32ToUtf8
:relfileprefix: ../../../
:mrdocs:

Unless `dstCapacity &equals;&equals; 0`, load into the specified `dstBuffer` all or as many complete `UTF&hyphen;8` sequences converted from the specified `srcString` of UTF&hyphen;32 as will fit, along with an always&hyphen;present terminating null byte, into the specified `dstCapacity` bytes, and return 0 on success or a bit&hyphen;wise OR of `CharConvertStatus&colon;&colon;k&lowbar;INVALID&lowbar;INPUT&lowbar;BIT` if invalid `UTF&hyphen;32` values (in the range `&lsqb;0xD800 &period;&period; 0xDFFF&rsqb;` or above 0x10FFFF) are seen and `CharConvertStatus&colon;&colon;k&lowbar;OUT&lowbar;OF&lowbar;SPACE&lowbar;BIT` if there is insufficient room for the entire result to be written&period; If `dstCapacity &equals;&equals; 0` return `CharConvertStatus&colon;&colon;k&lowbar;INVALID&lowbar;OUT&lowbar;OF&lowbar;SPACE&lowbar;BIT` without modifying `dstBuffer`&period; Optionally specify `srcStringlength` as the number of `UTF&hyphen;32` values to be converted&period; If `srcStringLength` is specified, convert that many UTF&hyphen;32 values from `srcString` (including zero values), otherwise convert values up to but not including a terminating zero value&period; Optionally specify `numCodePointsWritten` to receive the number of `UTF&hyphen;8` code points written to `dstBuffer`&period; Optionally specify `numBytesWritten` to receive the number of bytes written to `dstBuffer`&period; Optionally specify `errorByte` as the character to be written to `dstBuffer` as the translation of invalid `UTF&hyphen;32` values&semi; if not specified, `?` is used, and if given as 0, no character is written at all&period; Optionally specify `byteOrder` to determine how `UTF&hyphen;32` values in `srcString` are interpreted&semi; if not given, host byte order is used&period; The behavior is undefined if `errorByte` is 0x80 or above&period; Note that if you are passing the `bsl&colon;&colon;vector&lt;unsigned int&gt;` obtained from a call to `utf8ToUtf32` and using `srcStringLength`, you must take care to pass `vector&period;size() &hyphen; 1` to `srcStringLength` to avoid embedding the terminating 0&period;

== Synopsis

Declared in `&lt;bdlde&lowbar;charconvertutf32&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf32ToUtf8(
    char* dstBuffer,
    std::size&lowbar;t dstCapacity,
    unsigned int const* srcString,
    std::size&lowbar;t* numCodePointsWritten = 0,
    std::size&lowbar;t* numBytesWritten = 0,
    unsigned char errorByte = &apos;?&apos;,
    xref:BloombergLP/bdlde/ByteOrder/Enum.adoc[ByteOrder::Enum] byteOrder = ByteOrder&colon;&colon;e&lowbar;HOST);
----


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