Logo Search packages:      
Sourcecode: icu version File versions

CharacterIterator Class Reference

#include <chariter.h>

Inheritance diagram for CharacterIterator:

ForwardCharacterIterator UObject UMemory UCharCharacterIterator StringCharacterIterator

List of all members.

Detailed Description

Abstract class that defines an API for iteration on text objects. This is an interface for forward and backward iteration and random access into a text object.

The API provides backward compatibility to the Java and older ICU CharacterIterator classes but extends them significantly:

  1. CharacterIterator is now a subclass of ForwardCharacterIterator.
  2. While the old API functions provided forward iteration with "pre-increment" semantics, the new one also provides functions with "post-increment" semantics. They are more efficient and should be the preferred iterator functions for new implementations. The backward iteration always had "pre-decrement" semantics, which are efficient.
  3. Just like ForwardCharacterIterator, it provides access to both code units and code points. Code point access versions are available for the old and the new iteration semantics.
  4. There are new functions for setting and moving the current position without returning a character, for efficiency.

See ForwardCharacterIterator for examples for using the new forward iteration functions. For backward iteration, there is also a hasPrevious() function that can be used analogously to hasNext(). The old functions work as before and are shown below.

Examples for some of the new functions:

Forward iteration with hasNext():

 void forward1(CharacterIterator &it) {
     UChar32 c;
     for(it.setToStart(); it.hasNext();) {
         // use c
Forward iteration more similar to loops with the old forward iteration, showing a way to convert simple for() loops:
 void forward2(CharacterIterator &it) {
     UChar c;
     for(c=it.firstPostInc(); c!=CharacterIterator::DONE; c=it.nextPostInc()) {
          // use c
Backward iteration with setToEnd() and hasPrevious():
  void backward1(CharacterIterator &it) {
      UChar32 c;
      for(it.setToEnd(); it.hasPrevious();) {
          // use c
Backward iteration with a more traditional for() loop:
 void backward2(CharacterIterator &it) {
     UChar c;
     for(c=it.last(); c!=CharacterIterator::DONE; c=it.previous()) {
         // use c

Example for random access:

  void random(CharacterIterator &it) {
      // set to the third code point from the beginning
      it.move32(3, CharacterIterator::kStart);
      // get a code point from here without moving the position
      UChar32 c=it.current32();
      // get the position
      int32_t pos=it.getIndex();
      // get the previous code unit
      UChar u=it.previous();
      // move back one more code unit
      it.move(-1, CharacterIterator::kCurrent);
      // set the position back to where it was
      // and read the same code point c and move beyond it
      if(c!=it.next32PostInc()) {
          exit(1); // CharacterIterator inconsistent

Examples, especially for the old API:

Function processing characters, in this example simple output

  void processChar( UChar c )
      cout << " " << c;
Traverse the text from start to finish
  void traverseForward(CharacterIterator& iter)
      for(UChar c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
Traverse the text backwards, from end to start
  void traverseBackward(CharacterIterator& iter)
      for(UChar c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) {
Traverse both forward and backward from a given position in the text. Calls to notBoundary() in this example represents some additional stopping criteria.
 void traverseOut(CharacterIterator& iter, int32_t pos)
      UChar c;
      for (c = iter.setIndex(pos);
      c != CharacterIterator.DONE && (Unicode::isLetter(c) || Unicode::isDigit(c));
          c = iter.next()) {}
      int32_t end = iter.getIndex();
      for (c = iter.setIndex(pos);
          c != CharacterIterator.DONE && (Unicode::isLetter(c) || Unicode::isDigit(c));
          c = iter.previous()) {}
      int32_t start = iter.getIndex() + 1;
      cout << "start: " << start << " end: " << end << endl;
      for (c = iter.setIndex(start); iter.getIndex() < end; c = iter.next() ) {
Creating a StringCharacterIterator and calling the test functions
  void CharacterIterator_Example( void )
       cout << endl << "===== CharacterIterator_Example: =====" << endl;
       UnicodeString text("Ein kleiner Satz.");
       StringCharacterIterator iterator(text);
       cout << "----- traverseForward: -----------" << endl;
       traverseForward( iterator );
       cout << endl << endl << "----- traverseBackward: ----------" << endl;
       traverseBackward( iterator );
       cout << endl << endl << "----- traverseOut: ---------------" << endl;
       traverseOut( iterator, 7 );
       cout << endl << endl << "-----" << endl;

ICU 2.0

Definition at line 356 of file chariter.h.

Public Types

enum  { DONE = 0xffff }
enum  EOrigin { kStart, kCurrent, kEnd }

Public Member Functions

virtual CharacterIteratorclone (void) const =0
virtual UChar current (void) const =0
virtual UChar32 current32 (void) const =0
int32_t endIndex (void) const
virtual UChar first (void)=0
virtual UChar32 first32 (void)=0
virtual UChar32 first32PostInc (void)
virtual UChar firstPostInc (void)
virtual UClassID getDynamicClassID (void) const =0
int32_t getIndex (void) const
int32_t getLength () const
virtual void getText (UnicodeString &result)=0
virtual int32_t hashCode (void) const =0
virtual UBool hasNext ()=0
virtual UBool hasPrevious ()=0
virtual UChar last (void)=0
virtual UChar32 last32 (void)=0
virtual int32_t move (int32_t delta, EOrigin origin)=0
virtual int32_t move32 (int32_t delta, EOrigin origin)=0
virtual UChar next (void)=0
virtual UChar32 next32 (void)=0
virtual UChar32 next32PostInc (void)=0
virtual UChar nextPostInc (void)=0
UBool operator!= (const ForwardCharacterIterator &that) const
virtual UBool operator== (const ForwardCharacterIterator &that) const =0
virtual UChar previous (void)=0
virtual UChar32 previous32 (void)=0
virtual UChar setIndex (int32_t position)=0
virtual UChar32 setIndex32 (int32_t position)=0
int32_t setToEnd ()
int32_t setToStart ()
int32_t startIndex (void) const

Static Public Member Functions

static void U_EXPORT2 operator delete (void *, void *) U_NO_THROW
static void U_EXPORT2 operator delete (void *p) U_NO_THROW
static void U_EXPORT2 operator delete[] (void *p) U_NO_THROW
static void *U_EXPORT2 operator new (size_t, void *ptr) U_NO_THROW
static void *U_EXPORT2 operator new (size_t size) U_NO_THROW
static void *U_EXPORT2 operator new[] (size_t size) U_NO_THROW

Protected Member Functions

 CharacterIterator (const CharacterIterator &that)
 CharacterIterator (int32_t length, int32_t textBegin, int32_t textEnd, int32_t position)
 CharacterIterator (int32_t length, int32_t position)
 CharacterIterator (int32_t length)
 CharacterIterator ()
CharacterIteratoroperator= (const CharacterIterator &that)

Protected Attributes

int32_t begin
int32_t end
int32_t pos
int32_t textLength

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index