BloombergLP::bdlde::Utf8Util

This struct provides a namespace for static methods used for validating UTF-8 strings, for counting the number of Unicode code points in them, for advancing pointers through UTF-8 strings by a specified number of Unicode code points, for counting the number of bytes a UTF-8 leading substring occupies, for counting the number of bytes in a UTF-8 character, and for appending a Unicode character to a UTF-8 string.

Synopsis

Declared in <bdlde_utf8util.h>

struct Utf8Util;

Type Aliases

NameDescription
IntPtr This typedef is an alias to bsls::Types::IntPtr.
Uint64 This typedef is an alias to bsls::Types::Uint64.
UintPtr This typedef is an alias to bsls::Types::UintPtr.
size_type This typedef is an alias to bsls::Types::size_type.

Enums

NameDescription
Unnamed enum Substitution code point constants.
ErrorStatus Enumerate the error status values that are returned (possibly through an out parameter) from some methods in this utility. Note that some of the functions in this struct have a return value that is non-negative on success, and one of these values when an error occurs, so all of these values must be negative to distinguish them from a "success" value.

Static Member Functions

NameDescription
advanceIfValid advanceIfValid overloads
advanceRaw advanceRaw overloads
appendUtf8Character Append the UTF-8 encoding of the specified Unicode codePoint to the specified output string. Return 0 on success, and a non-zero value otherwise.
appendUtf8CodePoint appendUtf8CodePoint overloads
codePointValue Return the numeric value of the UTF-8-encoded code point beginning at the specified codePoint. The behavior is undefined unless codePoint is the address of the first byte of a valid UTF-8 encoded character.
getByteSize Return the length (in bytes) of the UTF-8-encoded code point beginning at the specified codePoint. The behavior is undefined unless codePoint is the address of the first byte of a valid UTF-8 encoded character. Note that the value returned will be in the range [1 .. 4]. Also note that 1 is returned if 0 == *codePoint since '0' is a valid 1-byte encoding.
getLineAndColumnNumber getLineAndColumnNumber overloads
isValid isValid overloads
isValidCodePoint If the specified codePoint (having at least the specified numBytes) refers to a valid UTF-8 code point then return true and load the specified status with the number of bytes in the code-point; otherwise, if codePoint is not a valid code-point, return false and load status with one of the (negative) ErrorStatus constants. The behavior is undefined unless numBytes > 0.
numBytesIfValid Return the length (in bytes) of the specified numCodePoints UTF-8 encodings in the specified string, or a value less than 0 if string contains less than numCodePoints encodings. The behavior is undefined unless string refers to valid UTF-8. Note that string may contain more than numCodePoints encodings in which case the trailing ones are ignored.
numBytesInCodePoint Return the length (in bytes) of the UTF-8-encoded code point beginning at the specified codePoint. The behavior is undefined unless codePoint is the address of the first byte of a valid UTF-8 encoded character. Note that the value returned will be in the range [1 .. 4]. Also note that 1 is returned if 0 == *codePoint since '0' is a valid 1-byte encoding.
numBytesRaw Return the length (in bytes) of the specified numCodePoints UTF-8 encodings in the specified string, or a value less than 0 if string contains less than numCodePoints encodings. The behavior is undefined unless string refers to valid UTF-8. Note that string may contain more than numCodePoints encodings in which case the trailing ones are ignored.
numCharacters numCharacters overloads
numCharactersIfValid numCharactersIfValid overloads
numCharactersRaw numCharactersRaw overloads
numCodePointsIfValid numCodePointsIfValid overloads
numCodePointsRaw numCodePointsRaw overloads
readIfValid Read from the specified input and copy valid UTF-8 (only) to the specified outputBuffer having the specified outputBufferLength (in bytes). Load the specified status with: * 0 if input reached eof without encountering any invalid UTF-8 or prematurely exhausting outputBuffer. * A positive value if input was not completely read due to outputBuffer being filled (or nearly filled) without encountering any invalid UTF-8. * A negative value from ErrorStatus if invalid UTF-8 was encountered (without having written the invalid sequence to outputBuffer). Return the number of bytes of valid UTF-8 written to 'outputBuffer. If no invalid UTF-8 is encountered, or if input supports sputbackc with a putback buffer capacity of at least 4 bytes, input will be left positioned at the end of the valid UTF-8 read, otherwise, input will be left in an unspecified state. The behavior is undefined unless 4 <= outputBufferLength. Note that this function will stop reading input when less than 4 bytes of space remain in outputBuffer to prevent the possibility of a 4-byte UTF-8 sequence being truncated partway through.
replaceErrors replaceErrors overloads
toAscii Return the non-modifiable string representation of the ErrorStatus enumerator matching the specified value, if it exists, and "(* unrecognized value *)" otherwise. The string representation of an enumerator that matches value is the enumerator name with the "k_" prefix elided. Note that this method may be used to aid in interpreting status values that are returned from some methods in this utility. See ErrorStatus.