[#BloombergLP-bdlde-CharConvertUtf16-utf16ToUtf8-0fb]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlde.adoc[bdlde]::xref:BloombergLP/bdlde/CharConvertUtf16.adoc[CharConvertUtf16]::utf16ToUtf8
:relfileprefix: ../../../
:mrdocs:

Load into the specified `dstVector` the null‐terminated result of converting the specified UTF‐16 `*srcString` to its UTF‐8 equivalent. Optionally specify `srcLengthInWords`, the number of `unsigned short`s of input. If `srcLengthInWords` is not specified, the input must be terminated by a null word. Optionally specify `numCodePointsWritten`, which (if not 0) indicates the location of the modifiable variable into which the number of Unicode code points written, including the null terminator, is to be loaded, where one code point may occupy multiple bytes. Optionally specify an `errorByte` to be substituted (if not 0) for invalid encodings in the input string. Invalid encodings are incomplete multi‐word encodings or parts of a two‐word encoding out of their proper sequence. If `errorByte` is 0, invalid input sequences are ignored (i.e., produce no corresponding output). Optionally specify `byteOrder` to indicate the byte order of the UTF‐16 input; if `byteOrder` is not specified, the input is assumed to be in host byte order. Any previous contents of the destination are discarded. Return 0 on success and `CharConvertStatus::k_INVALID_INPUT_BIT` if one or more invalid sequences were encountered in the input. The behavior is undefined unless either `srcLengthInWords` is passed or `srcString` is null‐terminated, and `errorByte` is either 0 or a valid single‐byte Unicode code point (`0 < errorByte < 0x80`).

== Synopsis

Declared in `<bdlde_charconvertutf16.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf16ToUtf8(
    xref:bsl/vector-00d.adoc[bsl::vector<char>]* dstVector,
    unsigned short const* srcString,
    std::size_t* numCodePointsWritten = 0,
    char errorByte = '?',
    xref:BloombergLP/bdlde/ByteOrder/Enum.adoc[ByteOrder::Enum] byteOrder = ByteOrder::e_HOST);
----


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