Load into the specified dstBuffer of the specified dstCapacity, the result of converting the specified UTF-8 srcString to its UTF-32 equivalent. Optionally specify numCodePointsWritten, which (if not 0) indicates the location of the variable into which the number of Unicode code points (including the null terminator) written is to be loaded. Optionally specify 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, 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 code points are ignored (i.e., produce no corresponding output). 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 a bit-wise OR of the masks defined by CharConvertStatus::Enum otherwise, where CharConvertStatus::k_INVALID_INPUT_BIT will be set if one or more invalid sequences were encountered in the input, and CharConvertStatus::k_OUT_OF_SPACE_BIT will be set if the output space was exhausted before conversion was complete. 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 refers to an array of at least dstCapacity elements, srcString, if specified as a const char *, is null-terminated, and errorWord is either 0 or a valid UTF-32 code point (in the range [ 1 .. 0xd7ff ] or [ 0xe000 .. 0x10ffff ]). 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 (if that pointer is not 0), since there is insufficient space for even a null terminator alone. Also note that one Unicode code point always occupies one 32-bit word in UTF-32, but may occupy more than one byte of UTF-8, so that *numCodePointsWritten equals the number of words written. Also note that errorWord is assumed to be in host byte order.
Declared in <bdlde_charconvertutf32.h>
static
int
utf8ToUtf32(
unsigned int* dstBuffer,
std::size_t dstCapacity,
char const* srcString,
std::size_t* numCodePointsWritten = 0,
unsigned int errorWord = '?',
ByteOrder::Enum byteOrder = ByteOrder::e_HOST);