# Poco

# class TextIterator

Library: Foundation
Package: Text
Header: Poco/TextIterator.h

## Description

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.

## Member Summary

Member Functions: end, operator !=, operator *, operator ++, operator =, operator ==, swap

## Constructors

### TextIterator

TextIterator();

Creates an uninitialized TextIterator.

### TextIterator

TextIterator(
const std::string & str
);

Creates an end TextIterator for the given string.

### TextIterator

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

Creates an end TextIterator.

### TextIterator

TextIterator(
const TextIterator & it
);

Copy constructor.

### 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

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.

## Destructor

### ~TextIterator

~TextIterator();

Destroys the TextIterator.

## Member Functions

### end

TextIterator end() const;

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

### operator !=

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

Compares two iterators for inequality.

### operator *

int operator * () const;

Returns the Unicode value of the current character. If there is no valid character at the current position, -1 is returned.

### operator ++

TextIterator & operator ++ ();

Prefix increment operator.

### operator ++

TextIterator operator ++ (
int
);

Postfix increment operator.

### operator =

TextIterator & operator = (
const TextIterator & it
);

Assignment operator.

### operator ==

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

Compares two iterators for equality.

### swap

void swap(
TextIterator & it
);

Swaps the iterator with another one.