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

Load into the specified `dstVector` the result of converting the specified UTF‐8 `srcString` to its UTF‐16 equivalent. Optionally specify `numCodePointsWritten`, which (if not 0) indicates the location of the modifiable variable into which the number of UTF‐16 code points (including the null terminator) written is to be loaded. Optionally specify an `errorWord` to be substituted (if not 0) for invalid encodings in the input string. Invalid encodings are multi‐byte encoding parts out of sequence, non‐minimal UTF‐8 encodings, or code points outside the ranges that UTF‐16 can validly encode (in the range `[ 1 .. 0xd7ff ]` or `[ 0xe000 .. 0x10ffff ]`). If `errorWord` is 0, invalid input is ignored (i.e., produces no corresponding output). Optionally specify `byteOrder` to indicate the byte order of the UTF‐16 output; if `byteOrder` is not specified, the output 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` otherwise. The behavior is undefined unless `errorWord` is either 0 or a valid single‐word encoded UTF‐16 code point (in the range `[ 1 .. 0xd7ff ]` or `[ 0xe000 .. 0xffff ]`) and `srcString` is null‐terminated when specified as a `const char *`. Note that one code point can occupy multiple 16‐bit words. Also note that the size of the result vector is always fitted to the null‐terminated result, including the terminating 0. Also note that if `srcString` is a `bslstl::StringRef`, it may contain embedded null bytes that will be translated to null words embedded in the output.

== Synopsis

Declared in `<bdlde_charconvertutf16.h>`

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


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