StringCharacterIterator (Java Platform SE 8 )
Keywords: java.text.StringCharacterIterator class
Date: 2026-04-24

compact1, compact2, compact3
java.text

## Class StringCharacterIterator

- java.lang.Object
- - java.text.StringCharacterIterator

- All Implemented Interfaces:
    Cloneable, CharacterIterator

      public final class StringCharacterIterator
      extends Object
      implements CharacterIterator

  `StringCharacterIterator` implements the `CharacterIterator` protocol for a `String`. The `StringCharacterIterator` class iterates over the entire `String`.
  See Also:
    `CharacterIterator`

- - ### Field Summary

    - ### Fields inherited from interface java.text.CharacterIterator

      `DONE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StringCharacterIterator(String text)` Constructs an iterator with an initial index of 0.
    `StringCharacterIterator(String text, int pos)` Constructs an iterator with the specified initial index.
    `StringCharacterIterator(String text, int begin, int end, int pos)` Constructs an iterator over the given range of the given string, with the index set at the specified position.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `clone()` Creates a copy of this iterator.
    `char` | `current()` Implements CharacterIterator.current() for String.
    `boolean` | `equals(Object obj)` Compares the equality of two StringCharacterIterator objects.
    `char` | `first()` Implements CharacterIterator.first() for String.
    `int` | `getBeginIndex()` Implements CharacterIterator.getBeginIndex() for String.
    `int` | `getEndIndex()` Implements CharacterIterator.getEndIndex() for String.
    `int` | `getIndex()` Implements CharacterIterator.getIndex() for String.
    `int` | `hashCode()` Computes a hashcode for this iterator.
    `char` | `last()` Implements CharacterIterator.last() for String.
    `char` | `next()` Implements CharacterIterator.next() for String.
    `char` | `previous()` Implements CharacterIterator.previous() for String.
    `char` | `setIndex(int p)` Implements CharacterIterator.setIndex() for String.
    `void` | `setText(String text)` Reset this iterator to point to a new string.

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### StringCharacterIterator

          public StringCharacterIterator(String text)

      Constructs an iterator with an initial index of 0.
      Parameters:
        `text` - the `String` to be iterated over

    - #### StringCharacterIterator

          public StringCharacterIterator(String text,
                                         int pos)

      Constructs an iterator with the specified initial index.
      Parameters:
        `text` - The String to be iterated over
        `pos` - Initial iterator position

    - #### StringCharacterIterator

          public StringCharacterIterator(String text,
                                         int begin,
                                         int end,
                                         int pos)

      Constructs an iterator over the given range of the given string, with the index set at the specified position.
      Parameters:
        `text` - The String to be iterated over
        `begin` - Index of the first character
        `end` - Index of the character following the last character
        `pos` - Initial iterator position

  - ### Method Detail

    - #### setText

          public void setText(String text)

      Reset this iterator to point to a new string. This package-visible method is used by other java.text classes that want to avoid allocating new StringCharacterIterator objects every time their setText method is called.
      Parameters:
        `text` - The String to be iterated over
      Since:
        1.2

    - #### first

          public char first()

      Implements CharacterIterator.first() for String.
      Specified by:
        `first` in interface `CharacterIterator`
      Returns:
        the first character in the text, or DONE if the text is empty
      See Also:
        `CharacterIterator.first()`

    - #### last

          public char last()

      Implements CharacterIterator.last() for String.
      Specified by:
        `last` in interface `CharacterIterator`
      Returns:
        the last character in the text, or DONE if the text is empty
      See Also:
        `CharacterIterator.last()`

    - #### setIndex

          public char setIndex(int p)

      Implements CharacterIterator.setIndex() for String.
      Specified by:
        `setIndex` in interface `CharacterIterator`
      Parameters:
        `p` - the position within the text. Valid values range from getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown if an invalid value is supplied.
      Returns:
        the character at the specified position or DONE if the specified position is equal to getEndIndex()
      See Also:
        `CharacterIterator.setIndex(int)`

    - #### current

          public char current()

      Implements CharacterIterator.current() for String.
      Specified by:
        `current` in interface `CharacterIterator`
      Returns:
        the character at the current position or DONE if the current position is off the end of the text.
      See Also:
        `CharacterIterator.current()`

    - #### next

          public char next()

      Implements CharacterIterator.next() for String.
      Specified by:
        `next` in interface `CharacterIterator`
      Returns:
        the character at the new position or DONE if the new position is off the end of the text range.
      See Also:
        `CharacterIterator.next()`

    - #### previous

          public char previous()

      Implements CharacterIterator.previous() for String.
      Specified by:
        `previous` in interface `CharacterIterator`
      Returns:
        the character at the new position or DONE if the current position is equal to getBeginIndex().
      See Also:
        `CharacterIterator.previous()`

    - #### getBeginIndex

          public int getBeginIndex()

      Implements CharacterIterator.getBeginIndex() for String.
      Specified by:
        `getBeginIndex` in interface `CharacterIterator`
      Returns:
        the index at which the text begins.
      See Also:
        `CharacterIterator.getBeginIndex()`

    - #### getEndIndex

          public int getEndIndex()

      Implements CharacterIterator.getEndIndex() for String.
      Specified by:
        `getEndIndex` in interface `CharacterIterator`
      Returns:
        the index after the last character in the text
      See Also:
        `CharacterIterator.getEndIndex()`

    - #### getIndex

          public int getIndex()

      Implements CharacterIterator.getIndex() for String.
      Specified by:
        `getIndex` in interface `CharacterIterator`
      Returns:
        the current index.
      See Also:
        `CharacterIterator.getIndex()`

    - #### equals

          public boolean equals(Object obj)

      Compares the equality of two StringCharacterIterator objects.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `obj` - the StringCharacterIterator object to be compared with.
      Returns:
        true if the given obj is the same as this StringCharacterIterator object; false otherwise.
      See Also:
        `Object.hashCode()`, `HashMap`

    - #### hashCode

          public int hashCode()

      Computes a hashcode for this iterator.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        A hash code
      See Also:
        `Object.equals(java.lang.Object)`, `System.identityHashCode(java.lang.Object)`

    - #### clone

          public Object clone()

      Creates a copy of this iterator.
      Specified by:
        `clone` in interface `CharacterIterator`
      Overrides:
        `clone` in class `Object`
      Returns:
        A copy of this
      See Also:
        `Cloneable`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.