Convert the UTF‐8 srcString into UTF‐32 in dstVector.

Synopsis

Declared in <bdlde_charconvertutf32.h>

static
int
utf8ToUtf32(
    bsl::vector<unsigned int>* dstVector,
    char const* srcString,
    unsigned int errorWord = '?',
    ByteOrder::Enum byteOrder = ByteOrder::e_HOST);

Description

Load into the specified dstVector the result of converting the specified UTF‐8 srcString to its UTF‐32 equivalent. Optionally specify errorWord to be substituted, if not 0, for invalid encodings in the input string. Optionally specify byteOrder to indicate the byte order of the UTF‐32 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, UTF‐8 encodings more than four bytes in length, or code points outside the ranges that UTF‐32 can validly encode (i.e., [ 1 .. 0xd7ff ] and [ 0xe000 .. 0x10ffff ]). If errorWord is 0, invalid input sequences are ignored (i.e., produce no corresponding output). Any previous contents of the destination are discarded. The behavior is undefined unless srcString is null‐terminated when specified as a const char *, and unless errorWord is either 0 or a valid Unicode code point. Note that one code point always occupies one 32‐bit *ord of output; there is no numCodePointsWritten argument since, after the call, dstVector‐>size() will equal the number of code points written. Also note that when the input is a bsl::string_view, it may contain embedded nulls, which are translated to zeroes in the output. Also note that errorWord is assumed to be in host byte order.

Return Value

0 on success and CharConvertStatus::k_INVALID_INPUT_BIT otherwise

Parameters

Name

Description

dstVector

destination for the UTF‐32 conversion result

srcString

null‐terminated UTF‐8 source string to convert

errorWord

optional substitute for invalid encodings; 0 ignores them

byteOrder

byte order of the UTF‐32 output (host by default)

Created with MrDocs