StringCharacterIterator (Java SE 25 & JDK 25)
Description: declaration: module: java.base, package: java.text, class: StringCharacterIterator
Keywords: java.text.StringCharacterIterator class

# 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`. All constructors throw `NullPointerException` if `text` is `null`.

Since:
  1.1
See Also:
  - `CharacterIterator`

- ## Field Summary

  ### Fields declared in interface CharacterIterator

  `DONE`

- ## Constructor Summary

  Constructors
  Constructor
  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

  Modifier and Type
  Method
  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 declared in class Object

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

- ## Constructor Details

  - ### 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
    Throws:
      `IllegalArgumentException` - if `pos` is not within the bounds of range (inclusive) from `0` to the length of `text`

  - ### 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
    Throws:
      `IllegalArgumentException` - if `begin` and `end` are not within the bounds of range (inclusive) from `0` to the length of `text`, `begin` is greater than `end`, or `pos` is not within the bounds of range (inclusive) from `begin` to `end`

- ## Method Details

  - ### 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
    Throws:
      `NullPointerException` - if `text` is `null`
    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()
    Throws:
      `IllegalArgumentException` - if `p` is not within the bounds (inclusive) of `getBeginIndex()` 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(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`