Convert UTF‐32 from srcString into UTF‐8 in dstBuffer.

Synopsis

Declared in <bdlde_charconvertutf32.h>

static
int
utf32ToUtf8(
    char* dstBuffer,
    std::size_t dstCapacity,
    unsigned int const* srcString,
    std::size_t* numCodePointsWritten = 0,
    std::size_t* numBytesWritten = 0,
    unsigned char errorByte = '?',
    ByteOrder::Enum byteOrder = ByteOrder::e_HOST);

Description

Unless dstCapacity == 0, load into the specified dstBuffer all or as many complete UTF‐8 sequences converted from the specified srcString of UTF‐32 as will fit, along with an always‐present terminating null byte, into the specified dstCapacity bytes, and return 0 on success or a bit‐wise OR of CharConvertStatus::k_INVALID_INPUT_BIT if invalid UTF‐32 values (in the range [0xD800 .. 0xDFFF] or above 0x10FFFF) are seen and CharConvertStatus::k_OUT_OF_SPACE_BIT if there is insufficient room for the entire result to be written. If dstCapacity == 0 return CharConvertStatus::k_INVALID_OUT_OF_SPACE_BIT without modifying dstBuffer. Optionally specify srcStringlength as the number of UTF‐32 values to be converted. If srcStringLength is specified, convert that many UTF‐32 values from srcString (including zero values), otherwise convert values up to but not including a terminating zero value. Optionally specify numCodePointsWritten to receive the number of UTF‐8 code points written to dstBuffer. Optionally specify numBytesWritten to receive the number of bytes written to dstBuffer. Optionally specify errorByte as the character to be written to dstBuffer as the translation of invalid UTF‐32 values; if not specified, ? is used, and if given as 0, no character is written at all. Optionally specify byteOrder to determine how UTF‐32 values in srcString are interpreted; if not given, host byte order is used. The behavior is undefined if errorByte is 0x80 or above. Note that if you are passing the bsl::vector<unsigned int> obtained from a call to utf8ToUtf32 and using srcStringLength, you must take care to pass vector.size() ‐ 1 to srcStringLength to avoid embedding the terminating 0.

Return Value

0 on success or a bit‐wise OR of CharConvertStatus flags otherwise

Parameters

Name

Description

dstBuffer

buffer for the UTF‐8 conversion result

dstCapacity

capacity of dstBuffer in bytes

srcString

null‐terminated UTF‐32 source string to convert

numCodePointsWritten

if non‐null, receives the number of UTF‐8 code points written

numBytesWritten

if non‐null, receives the number of bytes written

errorByte

optional substitute for invalid UTF‐32 values; 0 writes nothing

byteOrder

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

Created with MrDocs