# 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`
Modifier and Type
Field
Description
`static final char`
`DONE`
Constant that is returned when the iterator has reached either the end or the beginning of the text.

## 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`
Modifier and Type
Method
Description
`protected void`
`finalize()`
Deprecated, for removal: This API element is subject to removal in a future version.
Finalization is deprecated and subject to removal in a future release.
`final Class<?>`
`getClass()`
Returns the runtime class of this `Object`.
`final void`
`notify()`
Wakes up a single thread that is waiting on this object's monitor.
`final void`
`notifyAll()`
Wakes up all threads that are waiting on this object's monitor.
`String`
`toString()`
Returns a string representation of the object.
`final void`
`wait()`
Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`
`wait(long timeoutMillis)`
Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`
`wait(long timeoutMillis, int nanos)`
Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

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