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

Synopsis

Declared in <bdlde_charconvertutf16.h>

static
int
utf8ToUtf16(
    bsl::wstring* dstString,
    std::string_view const& srcString,
    std::size_t* numCodePointsWritten = 0,
    wchar_t errorWord = '?',
    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

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

Created with MrDocs