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

Name

Description

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

Name

Description

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

Name

Description

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.

Created with MrDocs