BloombergLP::bdlde::CharConvertUtf16::utf16ToUtf8

Load, into the specified dstBuffer of the specified dstCapacity, 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 (including the terminating 0, if any) written is to be loaded, where one code point can occupy multiple bytes. Optionally specify numBytesWritten, which (if not 0) indicates the location of the modifiable variable into which the number of bytes written (including the null terminator, if any) is to be loaded. 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). 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 a bitwise‐or of the flags defined by CharConvertStatus::Enum otherwise. 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. The behavior is undefined unless dstBuffer refers to an array of at least dstCapacity elements, errorByte is either 0 or a valid single‐byte Unicode code point (0 < errorByte < 0x80), and srcString is null‐terminated if supplied as a pointer. Note that if dstCapacity is 0, this function returns CharConvertStatus::k_OUT_OF_SPACE_BIT set and 0 is written into *numCodePointsWritten and *numBytesWritten (if those pointers are non‐null), since there is insufficient space for even a null terminator alone. Also note that since UTF‐8 is a variable‐length encoding, numBytesWritten may be up to four times numCodePointsWritten, and therefore that an input srcString of dstCapacity code points (including the terminating 0, if present) may not fit into dstBuffer. A one‐word (two‐byte) UTF‐16 code point will require one to three UTF‐8 octets (bytes); a two‐word (four‐byte) UTF‐16 code point will always require four UTF‐8 octets. Also note that the amount of room needed will vary with the contents of the data and the language being translated, but never will the number of bytes output exceed three times the number of words input. Also note that, if dstCapacity > 0, then, after completion, strlen(dstBuffer) + 1 == *numBytesWritten. Also note that if srcString is a bslstl::StringRef, it may contain embedded 0 words that will be translated to null bytes embedded in the output.