[#BloombergLP-bdlde-CharConvertUcs2-utf8ToUcs2-0d2]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlde.adoc[bdlde]::xref:BloombergLP/bdlde/CharConvertUcs2.adoc[CharConvertUcs2]::utf8ToUcs2
:relfileprefix: ../../../
:mrdocs:

Load, into the specified `dstBuffer` of the specified `dstCapacity`, the result of converting the specified null‐terminated UTF‐8 `srcString` to its UCS‐2 equivalent. Optionally specify `numCharsWritten` which (if non‐zero) indicates the modifiable integer into which the number of characters written (including the null terminator) is to be loaded. Optionally specify `errorCharacter` to be substituted for invalid (i.e., not convertible to UCS‐2) input characters. If `errorCharacter` is 0, invalid input characters are ignored (i.e., produce no corresponding output characters). Return 0 on success and a bitwise‐or of the masks specified by `CharConvertStatus::Enum` otherwise, with `CharConvertStatus::k_INVALID_INPUT_BIT` set to indicate that at least one invalid input sequence was encountered, and `CharConvertStatus::k_OUT_OF_SPACE_BIT` set to indicate that `dstCapacity` was insufficient to accommodate the output. If `dstCapacity` was insufficient, the maximal null‐terminated prefix of the properly converted result string is loaded into `dstBuffer`, and (unless null) `*numCharsWritten` is set to `dstCapacity`. The behavior is undefined unless `0 <= dstCapacity`, `dstBuffer` refers to an array of at least `dstCapacity` elements, and `srcString` is null‐terminated. Note that if `dstCapacity` is 0, this function returns exactly 2 and `*numCharsWritten` (if specified) is loaded with 0 (since there is insufficient space for the null terminator even for an empty input string).

== Synopsis

Declared in `<bdlde_charconvertucs2.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf8ToUcs2(
    unsigned short* dstBuffer,
    std::size_t dstCapacity,
    char const* srcString,
    std::size_t* numCharsWritten = 0,
    unsigned short errorCharacter = '?');
----


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