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

Synopsis

Declared in <bdlde_charconvertutf16.h>

static
int
utf16ToUtf8(
    bsl::string* dstString,
    unsigned short const* srcString,
    std::size_t* numCodePointsWritten = 0,
    char errorByte = '?',
    ByteOrder::Enum byteOrder = ByteOrder::e_HOST);

Description

Load into the specified dstString the result of converting the specified UTF‐16 srcString to its UTF‐8 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 null terminator, is to be loaded, where one code point may occupy multiple bytes. Optionally specify an errorByte to be substituted (if not 0) for invalid encodings in the input string. Invalid encodings are incomplete multi‐word encodings or parts of a two‐word encoding out of their proper sequence. If errorByte is 0, invalid input sequences are ignored (i.e., produce no corresponding output). Any previous contents of the destination are discarded. Optionally specify byteOrder to indicate the byte order of the UTF‐16 input; if byteOrder is not specified, the input is assumed to be in host byte order. Return 0 on success and CharConvertStatus::k_INVALID_INPUT_BIT if one or more invalid sequences were encountered in the input. The behavior is undefined unless errorByte is either 0 or a valid single‐byte Unicode code point (0 < errorByte < 0x80) and srcString is null‐terminated if supplied as a const wchar_t *. Note that if srcString is a bslstl::StringRefWide, it may contain embedded 0 words that will be translated to null bytes 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

errorByte

replacement for invalid input, or 0 to skip

byteOrder

UTF‐16 byte order; host order if unspecified

Created with MrDocs