Convert a null‐terminated UCS‐2 string to UTF‐8 in a fixed buffer.

Synopsis

Declared in <bdlde_charconvertucs2.h>

static
int
ucs2ToUtf8(
    char* dstBuffer,
    std::size_t dstCapacity,
    unsigned short const* srcString,
    std::size_t* numCharsWritten = 0,
    std::size_t* numBytesWritten = 0);

Description

Load, into the specified dstBuffer of the specified dstCapacity, the result of converting the specified null‐terminated UCS‐2 srcString to its UTF‐8 equivalent. Optionally specify numCharsWritten which (if not 0) indicates the modifiable integer into which the number of UTF‐8 characters written (including the null terminator) is to be loaded. Optionally specify numBytesWritten which (if not 0) indicates the modifiable integer into which the number of bytes written (including the null terminator) is to be loaded. Return 0 on success and a bitwise‐or of the masks specified by CharConvertStatus::Enum otherwise, with CharConvertStatus::k_INVALID_INPUT_BIT set to indicate that at least one invalid input sequence was encountered, and CharConvertStatus::k_OUT_OF_SPACE_BIT set to indicate that dstCapacity was insufficient to accommodate the output. If dstCapacity was insufficient, the maximal null‐terminated prefix of the properly converted result string is loaded into dstBuffer. The behavior is undefined unless 0 <= dstCapacity, dstBuffer refers to an array of at least dstCapacity elements, and srcString is null‐terminated. Note that if dstCapacity is 0, this function returns exactly 2 and *numCharsWritten and *numBytesWritten (if not null) are loaded with 0 (since there is insufficient space for the null terminator even for an empty input string). Also note that since UTF‐8 is a variable‐length encoding, it is possible for numBytesWritten to be greater than numCharsWritten, and therefore that an input srcString of dstCapacity ‐ 1 characters may not fit into dstBuffer.

Return Value

0 on success and a bitwise‐or of the masks specified by CharConvertStatus::Enum otherwise

Parameters

Name

Description

dstBuffer

output buffer for the UTF‐8 conversion

dstCapacity

capacity of dstBuffer in bytes

srcString

null‐terminated UCS‐2 input

numCharsWritten

if non‐null, receives UTF‐8 character count

numBytesWritten

if non‐null, receives byte count written

Created with MrDocs