class Poco::TextIterator

Overview

An unidirectional iterator for iterating over characters in a string. More…

#include <TextIterator.h>

class TextIterator
{
public:
    // construction

    TextIterator();

    TextIterator(
        const std::string& str,
        const TextEncoding& encoding
        );

    TextIterator(
        const std::string::const_iterator& begin,
        const std::string::const_iterator& end,
        const TextEncoding& encoding
        );

    TextIterator(const std::string& str);
    TextIterator(const std::string::const_iterator& end);
    TextIterator(const TextIterator& it);

    // methods

    TextIterator&
    operator=(const TextIterator& it);

    void
    swap(TextIterator& it);

    int
    operator*() const;

    TextIterator&
    operator++();

    TextIterator
    operator++(int);

    bool
    operator==(const TextIterator& it) const;

    bool
    operator!=(const TextIterator& it) const;

    TextIterator
    end() const;
};

Detailed Documentation

An unidirectional iterator for iterating over characters in a string.

The TextIterator uses a TextEncoding object to work with multi-byte character encodings like UTF-8. Characters are reported in Unicode.

Example: Count the number of UTF-8 characters in a string.

UTF8Encoding utf8Encoding;
std::string utf8String("....");
TextIterator it(utf8String, utf8Encoding);
TextIterator end(utf8String);
int n = 0;
while (it != end) { ++n; ++it; }

NOTE: When an UTF-16 encoding is used, surrogate pairs will be reported as two separate characters, due to restrictions of the TextEncoding class.

For iterating over char buffers, see the TextBufferIterator class.

Construction

TextIterator()

Creates an uninitialized TextIterator.

TextIterator(
    const std::string& str,
    const TextEncoding& encoding
    )

Creates a TextIterator for the given string.

The encoding object must not be deleted as long as the iterator is in use.

TextIterator(
    const std::string::const_iterator& begin,
    const std::string::const_iterator& end,
    const TextEncoding& encoding
    )

Creates a TextIterator for the given range.

The encoding object must not be deleted as long as the iterator is in use.

TextIterator(const std::string& str)

Creates an end TextIterator for the given string.

TextIterator(const std::string::const_iterator& end)

Creates an end TextIterator.

TextIterator(const TextIterator& it)

Copy constructor.

Methods

TextIterator&
operator=(const TextIterator& it)

Assignment operator.

void
swap(TextIterator& it)

Swaps the iterator with another one.

int
operator*() const

Returns the Unicode value of the current character.

If there is no valid character at the current position, -1 is returned.

TextIterator&
operator++()

Prefix increment operator.

TextIterator
operator++(int)

Postfix increment operator.

bool
operator==(const TextIterator& it) const

Compares two iterators for equality.

bool
operator!=(const TextIterator& it) const

Compares two iterators for inequality.

TextIterator
end() const

Returns the end iterator for the range handled by the iterator.