[#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 == 0`, load into the specified `dstBuffer` all or as many complete `UTF‐8` sequences converted from the specified `srcString` of UTF‐32 as will fit, along with an always‐present terminating null byte, into the specified `dstCapacity` bytes, and return 0 on success or a bit‐wise OR of `CharConvertStatus::k_INVALID_INPUT_BIT` if invalid `UTF‐32` values (in the range `[0xD800 .. 0xDFFF]` or above 0x10FFFF) are seen and `CharConvertStatus::k_OUT_OF_SPACE_BIT` if there is insufficient room for the entire result to be written. If `dstCapacity == 0` return `CharConvertStatus::k_INVALID_OUT_OF_SPACE_BIT` without modifying `dstBuffer`. Optionally specify `srcStringlength` as the number of `UTF‐32` values to be converted. If `srcStringLength` is specified, convert that many UTF‐32 values from `srcString` (including zero values), otherwise convert values up to but not including a terminating zero value. Optionally specify `numCodePointsWritten` to receive the number of `UTF‐8` code points written to `dstBuffer`. Optionally specify `numBytesWritten` to receive the number of bytes written to `dstBuffer`. Optionally specify `errorByte` as the character to be written to `dstBuffer` as the translation of invalid `UTF‐32` values; if not specified, `?` is used, and if given as 0, no character is written at all. Optionally specify `byteOrder` to determine how `UTF‐32` values in `srcString` are interpreted; if not given, host byte order is used. The behavior is undefined if `errorByte` is 0x80 or above. Note that if you are passing the `bsl::vector<unsigned int>` obtained from a call to `utf8ToUtf32` and using `srcStringLength`, you must take care to pass `vector.size() ‐ 1` to `srcStringLength` to avoid embedding the terminating 0.

== Synopsis

Declared in `<bdlde_charconvertutf32.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf32ToUtf8(
    char* dstBuffer,
    std::size_t dstCapacity,
    unsigned int const* srcString,
    std::size_t* numCodePointsWritten = 0,
    std::size_t* numBytesWritten = 0,
    unsigned char errorByte = '?',
    xref:BloombergLP/bdlde/ByteOrder/Enum.adoc[ByteOrder::Enum] byteOrder = ByteOrder::e_HOST);
----


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