carb::extras::Utf8Iterator

class Utf8Iterator

A simple iterator class for walking a UTF-8 string.

This is built on top of the UTF8Parser static class and uses its functionality. Strings can only be walked forward. Random access to codepoints in the string is not possible. If needed, the pointer to the start of the next codepoint or the codepoint index can be retrieved.

Unnamed Group

using CodeByte = Utf8Parser::CodeByte 

Reference the types used in Utf8Parser for more convenient use locally.

The base type for a point in a UTF-8 string.

Ideally these values should point to the start of an encoded codepoint in a string.

using CodePoint = Utf8Parser::CodePoint 

The base type for a single Unicode codepoint value.

This represents a decoded UTF-8 codepoint.

using Flags = Utf8Parser::Flags : Base type for flags to various encoding and decoding functions.

Public Functions

inline Utf8Iterator()

inline Utf8Iterator(const CodeByte *string, size_t lengthInBytes = kNullTerminated, Flags flags = 0)

Constructor: initializes a new iterator for a given string.

Parameters

string – [in] The string to walk. This should be a UTF-8 encoded string. This can be nullptr, but the iterator will not be valid if so.
lengthInBytes – [in] The maximum number of bytes to walk in the string. This may be kNullTerminated if the string is null terminated. If the string is unterminated or only a portion of it needs to be iterated over, this may be the size of the buffer in bytes.
flags – [in] Flags to control the behavior of the UTF-8 parser. This may be zero or more of the Utf8Parser::fDecode* flags.

Returns

No return value.

inline Utf8Iterator(const Utf8Iterator &it)

Copy constructor: copies another iterator into this one.

Parameters: it – [in] The iterator to be copied. Note that if it is invalid, this iterator will also become invalid.
Returns: No return value.

inline operator bool() const

Checks if this iterator is still valid.

Returns: true if this iterator still has at least one more codepoint to walk.
Returns: false if there is no more string data to walk and decode.

inline bool operator!() const

Check is this iterator is invalid.

Returns: true if there is no more string data to walk and decode.
Returns: false if this iterator still has at least one more codepoint to walk.

inline CodePoint operator*() const

Retrieves the codepoint at this iterator’s current location.

Returns: The codepoint at the current location in the string. Calling this multiple times does not cause the decoding work to be done multiple times. The decoded codepoint is cached once decoded.
Returns: 0 if there are no more codepoints to walk in the string.

inline const CodeByte *operator&() const

Retrieves the address of the start of the current codepoint.

Returns: The address of the start of the current codepoint for this iterator. This can be used as a way of copying, editing, or reworking the string during iteration. It is the caller’s responsibility to ensure the string is still properly encoded after any change.
Returns: nullptr if there is no more string data to walk.

inline Utf8Iterator &operator++()

Pre increment operator: walk to the next codepoint in the string.

Returns: A reference to this iterator. Note that if the end of the string is reached, the new state of this iterator will first point to the null terminator in the string (for null terminated strings), then after another increment will return the address nullptr from the ‘&’ operator. For length limited strings, reaching the end will immediately return nullptr from the ‘&’ operator.

inline Utf8Iterator operator++(int32_t)

Post increment operator: walk to the next codepoint in the string.

Returns: A new iterator object representing the state of this object before the increment operation.

template<typename T> inline Utf8Iterator &operator+=(T count)

Increment operator: skip over zero or more codepoints in the string.

Parameters: count – [in] The number of codepoints to skip over. This may be zero or larger. Negative values will be ignored and the iterator will not advance.
Returns: A reference to this iterator.

template<typename T> inline Utf8Iterator operator+(T count) const

Addition operator: create a new iterator that skips zero or more codepoints.

Parameters: count – [in] The number of codepoints to skip over. This may be zero or larger. Negative values will be ignored and the iterator will not advance.
Returns: A new iterator that has skipped over the next count codepoints in the string starting from the location of this iterator.

inline bool operator==(const Utf8Iterator &it) const

Comparison operators.

Remark