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

Convert the UTF‐8 source to UTF‐16 in the destination.

== Synopsis

Declared in `<bdlde_charconvertutf16.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf8ToUtf16(
    xref:bsl/wstring.adoc[bsl::wstring]* dstString,
    std::string_view const& srcString,
    std::size_t* numCodePointsWritten = 0,
    wchar_t errorWord = '?',
    xref:BloombergLP/bdlde/ByteOrder/Enum.adoc[ByteOrder::Enum] byteOrder = ByteOrder::e_HOST);
----

== Description

Load into the specified `dstString` 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 Unicode code points written, including the terminating null character, is to be loaded. Optionally specify an `errorChar` to be substituted, if not 0, for invalid encodings in the input string. 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. Return 0 on success and `CharConvertStatus::k_INVALID_INPUT_BIT` otherwise. Invalid encodings are multi‐byte encoding parts out of sequence, non‐minimal UTF‐8 encodings of code points, or code points outside the ranges that UTF‐16 can validly encode (in the range `[ 1 .. 0xd7ff ]` or `[ 0xe000 .. 0x10ffff ]`). If `errorChar` is 0, invalid input code points are ignored (i.e., produce no corresponding output). The behavior is undefined unless `srcString` is null‐terminated when specified as a `const char *`. Note that one code point can occupy multiple UTF‐16 words, and that if `srcString` is a `bslstl::StringRef`, it may contain embedded null bytes that will be translated to null words embedded in the output.

== Return Value

0 on success and `CharConvertStatus::k_INVALID_INPUT_BIT` otherwise

== Parameters

[cols="1,4"]
|===
| Name| Description
| *dstString*
| destination for the converted output
| *srcString*
| source string to convert
| *numCodePointsWritten*
| if non‐null, set to the code‐point count written
| *errorWord*
| replacement for invalid input, or 0 to skip
| *byteOrder*
| UTF‐16 byte order; host order if unspecified
|===


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