Load into the specified dstBuffer of the specified dstCapacity, 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 variable into which the number of UTF-16 code points (including the terminating 0) written is to be loaded. 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. 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 of code points, or code points outside the ranges that UTF-16 can validly encode (in the range [ 1 .. 0xd7ff ] or [ 0xde00 .. 0x10ffff ]). 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. If errorWord is 0, invalid input sequences are ignored (i.e., produce no corresponding output). Return 0 on success and a bit-wise or of the bits specified by CharConvertStatus::Enum otherwise to indicate that there were invalid sequences or if dstCapacity was inadequate to store the output. If dstCapacity > 0 yet dstCapacity specifies a buffer too small to hold the output, the maximal null-terminated prefix of the properly converted result string is loaded into dstBuffer. 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-word encoded UTF-16 code point (in the range [ 1 .. 0xd7ff ] or [ 0xe000 .. 0xffff ]), and srcString is null-terminated if supplied as a const char *. Note that if dstCapacity is 0, *dstBuffer is not modified and this function returns a value with CharConvertStatus::k_OUT_OF_SPACE_BIT set and 0 is written into *numCodePointsWritten and *numWordsWritten (if those pointers are non-null), since there is insufficient space for even a null terminator alone. Also note that one code point can occupy multiple 16-bit words, so that *numWordsWritten may be greater than *numCodePointsWritten, and therefore that an input srcString of dstCapacity code points may not fit into dstBuffer. However, an input srcString of dstCapacity bytes (including terminating 0, if present) will always fit (since the UTF-8 encoding of a code point requires at least as many bytes as the UTF-16 encoding requires words). 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.
Declared in <bdlde_charconvertutf16.h>
static
int
utf8ToUtf16(
char16_t* dstBuffer,
std::size_t dstCapacity,
std::string_view const& srcString,
std::size_t* numCodePointsWritten = 0,
std::size_t* numWordsWritten = 0,
char16_t errorChar = '?',
ByteOrder::Enum byteOrder = ByteOrder::e_HOST);