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

Convert the UTF&hyphen;8 source to UTF&hyphen;16 in the destination&period;

== Synopsis

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

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

== Description

Load into the specified `dstBuffer` of the specified `dstCapacity`, the result of converting the specified UTF&hyphen;8 `srcString` to its UTF&hyphen;16 equivalent&period; Optionally specify `numCodePointsWritten`, which (if not 0) indicates the location of the variable into which the number of UTF&hyphen;16 code points (including the terminating 0) written is to be loaded&period; Optionally specify `numWordsWritten`, which (if not 0) indicates the location of the modifiable variable into which the number of `short` _memory words_ written (including the null terminator) is to be loaded&period; Optionally specify an `errorWord` to be substituted (if not 0) for invalid encodings in the input string&period; Invalid encodings are multi&hyphen;byte encoding parts out of sequence, non&hyphen;minimal UTF&hyphen;8 encodings of code points, or code points outside the ranges that UTF&hyphen;16 can validly encode (in the range `&lsqb; 1 &period;&period; 0xd7ff &rsqb;` or `&lsqb; 0xde00 &period;&period; 0x10ffff &rsqb;`)&period; Optionally specify `byteOrder` to indicate the byte order of the UTF&hyphen;16 output&semi; if `byteOrder` is not specified, the output is assumed to be in host byte order&period; If `errorWord` is 0, invalid input sequences are ignored (i&period;e&period;, produce no corresponding output)&period; Return 0 on success and a bit&hyphen;wise or of the bits specified by `CharConvertStatus&colon;&colon;Enum` otherwise to indicate that there were invalid sequences or if `dstCapacity` was inadequate to store the output&period; If `dstCapacity &gt; 0` yet `dstCapacity` specifies a buffer too small to hold the output, the maximal null&hyphen;terminated prefix of the properly converted result string is loaded into `dstBuffer`&period; The behavior is undefined unless `dstBuffer`, if specified, refers to an array of at least `dstCapacity` elements, `errorWord` is either 0 or a valid single&hyphen;word encoded UTF&hyphen;16 code point (in the range `&lsqb; 1 &period;&period; 0xd7ff &rsqb;` or `&lsqb; 0xe000 &period;&period; 0xffff &rsqb;`), and `srcString` is null&hyphen;terminated if supplied as a `const char &ast;`&period; Note that if `dstCapacity` is 0, `&ast;dstBuffer` is not modified and this function returns a value with `CharConvertStatus&colon;&colon;k&lowbar;OUT&lowbar;OF&lowbar;SPACE&lowbar;BIT` set and 0 is written into `&ast;numCodePointsWritten` and `&ast;numWordsWritten` (if those pointers are non&hyphen;null), since there is insufficient space for even a null terminator alone&period; Also note that one code point can occupy multiple 16&hyphen;bit words, so that `&ast;numWordsWritten` may be greater than `&ast;numCodePointsWritten`, and therefore that an input `srcString` of `dstCapacity` code points may not fit into `dstBuffer`&period; However, an input `srcString` of `dstCapacity` bytes (including terminating 0, if present) will always fit (since the UTF&hyphen;8 encoding of a code point requires at least as many bytes as the UTF&hyphen;16 encoding requires words)&period; Also note that if `srcString` is a `bslstl&colon;&colon;StringRef`, it may contain embedded null bytes that will be translated to null words embedded in the output&period;

== Return Value

0 on success and a bitwise&hyphen;or of the bits specified by `CharConvertStatus&colon;&colon;Enum` otherwise

== Parameters

[cols="1,4"]
|===
| Name| Description
| *dstBuffer*
| destination buffer for the converted output
| *dstCapacity*
| capacity of `dstBuffer` in elements
| *srcString*
| source string to convert
| *numCodePointsWritten*
| if non&hyphen;null, set to the code&hyphen;point count written
| *numWordsWritten*
| if non&hyphen;null, set to the word count written
| *errorChar*
| replacement for invalid input, or 0 to skip
| *byteOrder*
| UTF&hyphen;16 byte order&semi; host order if unspecified
|===


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