Scala Library
scala.collection

trait Iterator
[source: scala/collection/Iterator.scala]
trait Iterator[+A]
extends AnyRef
Iterators are data structures that allow to iterate over a sequence of elements. They have a hasNext method for checking if there is a next element available, and a next method which returns the next element and discards it from the iterator.
Author
Martin Odersky, Matthias Zenger
Version
2.8
Direct Known Subclasses:
CountedIterator, BufferedIterator, JavaConversions.JIteratorWrapper, JavaConversions.JEnumerationWrapper, Source, Regex.MatchIterator, ProducerConsumerIterator
Method Summary
def ++ [B >: A](that : => Iterator[B]) : Iterator[B]
Returns a new iterator that first yields the elements of this iterator followed by the elements provided by iterator that.
def /: [B](z : B)(op : (B, A) => B) : B
Similar to foldLeft but can be used as an operator with the order of iterator and zero arguments reversed. That is, z /: xs is the same as xs foldLeft z.
def :\ [B](z : B)(op : (A, B) => B) : B
An alias for foldRight. That is, xs :\ z is the same as xs foldRight z.
def addString (buf : StringBuilder, sep : java.lang.String) : StringBuilder
Write all elements of this iterator into given string builder. The string representations of elements (w.r.t. the method toString()) are separated by the string sep.
def addString (buf : StringBuilder) : StringBuilder
Write all elements of this string into given string builder without using any separator between consecutive elements.
def addString (buf : StringBuilder, start : java.lang.String, sep : java.lang.String, end : java.lang.String) : StringBuilder
Write all elements of this iterator into given string builder. The written text begins with the string start and is finished by the string end. Inside, the string representations of elements (w.r.t. the method toString()) are separated by the string sep.
def append [B >: A](that : Iterator[B]) : Iterator[B]
Returns a new iterator that first yields the elements of this iterator followed by the elements provided by iterator that.
def buffered : BufferedIterator[A]
Returns a buffered iterator from this iterator.
def collect : Sequence[A]
Collect elements into a seq.
def contains (elem : Any) : Boolean
Tests if the given value elem is a member of this iterator.
def copyToArray [B >: A](xs : Array[B], start : Int) : Unit
Fills the given array xs with the elements of this iterator starting at position start until either the end of the current iterator or the end of array `xs` is reached.
def copyToArray [B >: A](xs : Array[B]) : Unit
Fills the given array xs with the elements of this iterator starting at position 0 until either the end of the current iterator or the end of array `xs` is reached.
def copyToArray [B >: A](xs : Array[B], start : Int, len : Int) : Unit
Fills the given array `xs` with at most `len` elements of this iterator starting at position `start` until either `len` elements have been copied, or the end of the iterator is reached, or the end of the array `xs` is reached.
def copyToBuffer [B >: A](dest : Buffer[B]) : Unit
Copy all elements to a buffer
def counted : CountedIterator[A]
Returns a counted iterator from this iterator.
def drop (n : Int) : Iterator[A]
Advances this iterator past the first n elements, or the length of the iterator, whichever is smaller.
def dropWhile (p : (A) => Boolean) : Iterator[A]
Skips longest sequence of elements of this iterator which satisfy given predicate p, and returns an iterator of the remaining elements.
def duplicate : (Iterator[A], Iterator[A])
Creates two new iterators that both iterate over the same elements as this iterator (in the same order).
def exists (p : (A) => Boolean) : Boolean
Apply a predicate p to all elements of this iterable object and return true iff there is at least one element for which p yields true.
def filter (p : (A) => Boolean) : Iterator[A]
Returns an iterator over all the elements of this iterator that satisfy the predicate p. The order of the elements is preserved.
def find (p : (A) => Boolean) : Option[A]
Find and return the first value returned by the iterator satisfying a predicate, if any.
def findIndexOf (p : (A) => Boolean) : Int
Returns index of the first element satisfying a predicate, or -1.
def flatMap [B](f : (A) => Iterator[B]) : Iterator[B]
Applies the given function f to each element of this iterator, then concatenates the results.
def foldLeft [B](z : B)(op : (B, A) => B) : B
Combines the elements of this iterator together using the binary operator op, from left to right, and starting with the value z.
def foldRight [B](z : B)(op : (A, B) => B) : B
Combines the elements of this iterator together using the binary operator op, from right to left, and starting with the value z.
def forall (p : (A) => Boolean) : Boolean
Apply a predicate p to all elements of this iterable object and return true iff the predicate yields true for all elements.
def foreach [U](f : (A) => U) : Unit
Execute a function f for all elements of this iterator.
abstract def hasNext : Boolean
Does this iterator provide another element?
def indexOf [B >: A](elem : B) : Int
Returns the index of the first occurence of the specified object in this iterable object.
def indexWhere (p : (A) => Boolean) : Int
Returns index of the first element satisfying a predicate, or -1.
def length : Int
Returns the number of elements in this iterator.
def map [B](f : (A) => B) : Iterator[B]
Returns a new iterator that maps all elements of this iterator to new elements using function f.
def mkString (sep : java.lang.String) : java.lang.String
Returns a string representation of this iterable object. The string representations of elements (w.r.t. the method toString()) are separated by the string sep.
def mkString : java.lang.String
Returns a string representation of this iterable object. The string representations of elements (w.r.t. the method toString()) are concatenated without any separator string.
def mkString (start : java.lang.String, sep : java.lang.String, end : java.lang.String) : java.lang.String
Returns a string representation of the elements in this iterator. The resulting string begins with the string start and is finished by the string end. Inside, the string representations of elements (w.r.t. the method toString) are separated by the string sep.

Ex:
List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"
abstract def next : A
Returns the next element of this iterator.
def padTo [A1 >: A](len : Int, elem : A1) : Iterator[A1]
Return a new iterator with a length equal or longer to `len`. If the current iterator returns fewer than `len` elements return `elem` until the required length `len` is reached.
def partition (p : (A) => Boolean) : (Iterator[A], Iterator[A])
Partitions this iterator in two iterators according to a predicate.
def patch [B >: A](from : Int, patchElems : Iterator[B], replaced : Int) : Iterator[B]
Returns this iterator with patched values.
def readInto [B >: A](xs : Array[B], start : Int, sz : Int) : Unit
Fills the given array xs with the elements of this sequence starting at position start. Like copyToArray, but designed to accomodate IO stream operations.
def readInto [B >: A](xs : Array[B], start : Int) : Unit
def readInto [B >: A](xs : Array[B]) : Unit
def reduceLeft [B >: A](op : (B, A) => B) : B
Combines the elements of this iterator together using the binary operator op, from left to right
def reduceLeftOpt [B >: A](op : (B, A) => B) : Option[B]
Combines the elements of this iterator together using the binary operator op, from left to right
def reduceRight [B >: A](op : (A, B) => B) : B
Combines the elements of this iterator together using the binary operator op, from right to left
def reduceRightOpt [B >: A](op : (A, B) => B) : Option[B]
Combines the elements of this iterable object together using the binary operator op, from right to left.
def slice (from : Int, until : Int) : Iterator[A]
Advances this iterator past the first `from` elements using `drop`, and then takes `until - from` elements, using `take`.
def take (n : Int) : Iterator[A]
Returns a new iterator that iterates only over the first n elements of this iterator, or the length of the iterator, whichever is smaller.
def takeWhile (p : (A) => Boolean) : Iterator[A]
Returns an iterator over the longest prefix of this iterator such that all elements of the result satisfy the predicate p. The order of the elements is preserved.
def toList : List[A]
Traverse this iterator and return all elements in a list.
def toSequence : Sequence[A]
Traverse this iterator and return all elements in a sequence.
def toStream : Stream[A]
Traverse this iterator and return all elements in a stream.
override def toString : java.lang.String
Returns a string representation of the object.
def zip [B](that : Iterator[B]) : Iterator[(A, B)]
Return an iterator formed from this iterator and the specified iterator that by associating each element of the former with the element at the same position in the latter. If one of the two iterators is longer than the other, its remaining elements are ignored.
def zipAll [B, A1 >: A, B1 >: B](that : Iterator[B], thisElem : A1, thatElem : B1) : Iterator[(A1, B1)]
Returns an iterator formed from this iterator and the specified iterator that by associating each element of the former with the element at the same position in the latter.
def zipWithIndex : Iterator[(A, Int)]
Return an iterator that pairs each element of this iterator with its index, counting from 0.
Methods inherited from AnyRef
getClass, hashCode, equals, clone, notify, notifyAll, wait, wait, wait, finalize, ==, !=, eq, ne, synchronized
Methods inherited from Any
==, !=, isInstanceOf, asInstanceOf
Method Details
abstract def hasNext : Boolean
Does this iterator provide another element?
abstract def next : A
Returns the next element of this iterator.
def take(n : Int) : Iterator[A]
Returns a new iterator that iterates only over the first n elements of this iterator, or the length of the iterator, whichever is smaller.
Parameters
n - the number of elements to take
Returns
the new iterator
def drop(n : Int) : Iterator[A]
Advances this iterator past the first n elements, or the length of the iterator, whichever is smaller.
Parameters
n - the number of elements to drop
Returns
the new iterator
def slice(from : Int, until : Int) : Iterator[A]
Advances this iterator past the first `from` elements using `drop`, and then takes `until - from` elements, using `take`.
Parameters
from - The index of the first element of the slice
until - The index of the element following the slice
def map[B](f : (A) => B) : Iterator[B]
Returns a new iterator that maps all elements of this iterator to new elements using function f.
def ++[B >: A](that : => Iterator[B]) : Iterator[B]
Returns a new iterator that first yields the elements of this iterator followed by the elements provided by iterator that.
def flatMap[B](f : (A) => Iterator[B]) : Iterator[B]
Applies the given function f to each element of this iterator, then concatenates the results.
Parameters
f - the function to apply on each element.
Returns
an iterator over f(a0), ... , f(an) if this iterator yields the elements a0, ..., an.
def filter(p : (A) => Boolean) : Iterator[A]
Returns an iterator over all the elements of this iterator that satisfy the predicate p. The order of the elements is preserved.
Parameters
p - the predicate used to filter the iterator.
Returns
the elements of this iterator satisfying p.
def takeWhile(p : (A) => Boolean) : Iterator[A]
Returns an iterator over the longest prefix of this iterator such that all elements of the result satisfy the predicate p. The order of the elements is preserved.
Parameters
p - the predicate used to filter the iterator.
Returns
the longest prefix of this iterator satisfying p.
def partition(p : (A) => Boolean) : (Iterator[A], Iterator[A])
Partitions this iterator in two iterators according to a predicate.
Parameters
p - the predicate on which to partition
Returns
a pair of iterators: the iterator that satisfies the predicate p and the iterator that does not. The relative order of the elements in the resulting iterators is the same as in the original iterator.
def dropWhile(p : (A) => Boolean) : Iterator[A]
Skips longest sequence of elements of this iterator which satisfy given predicate p, and returns an iterator of the remaining elements.
Parameters
p - the predicate used to skip elements.
Returns
an iterator consisting of the remaining elements
def zip[B](that : Iterator[B]) : Iterator[(A, B)]
Return an iterator formed from this iterator and the specified iterator that by associating each element of the former with the element at the same position in the latter. If one of the two iterators is longer than the other, its remaining elements are ignored.
def padTo[A1 >: A](len : Int, elem : A1) : Iterator[A1]
Return a new iterator with a length equal or longer to `len`. If the current iterator returns fewer than `len` elements return `elem` until the required length `len` is reached.
def zipWithIndex : Iterator[(A, Int)]
Return an iterator that pairs each element of this iterator with its index, counting from 0.
def zipAll[B, A1 >: A, B1 >: B](that : Iterator[B], thisElem : A1, thatElem : B1) : Iterator[(A1, B1)]
Returns an iterator formed from this iterator and the specified iterator that by associating each element of the former with the element at the same position in the latter.
Parameters
that - iterator that may have a different length as the self iterator.
thisElem - element thisElem is used to fill up the resulting iterator if the self iterator is shorter than that
thatElem - element thatElem is used to fill up the resulting iterator if that is shorter than the self iterator
Returns
Iterator((a0,b0), ..., (an,bn), (elem,bn+1), ..., {elem,bm}) when [a0, ..., an] zip [b0, ..., bm] is invoked where m > n.
def foreach[U](f : (A) => U) : Unit
Execute a function f for all elements of this iterator.
Parameters
f - a function that is applied to every element.
def forall(p : (A) => Boolean) : Boolean
Apply a predicate p to all elements of this iterable object and return true iff the predicate yields true for all elements.
Parameters
p - the predicate
Returns
true iff the predicate yields true for all elements.
def exists(p : (A) => Boolean) : Boolean
Apply a predicate p to all elements of this iterable object and return true iff there is at least one element for which p yields true.
Parameters
p - the predicate
Returns
true iff the predicate yields true for at least one element.
def contains(elem : Any) : Boolean
Tests if the given value elem is a member of this iterator.
Parameters
elem - element whose membership has to be tested.
def find(p : (A) => Boolean) : Option[A]
Find and return the first value returned by the iterator satisfying a predicate, if any.
Parameters
p - the predicate
Returns
the first element in the iterable object satisfying p, or None if none exists.
def indexWhere(p : (A) => Boolean) : Int
Returns index of the first element satisfying a predicate, or -1.
Notes
may not terminate for infinite-sized collections.
Parameters
p - the predicate
Returns
the index of the first element satisfying p, or -1 if such an element does not exist
def indexOf[B >: A](elem : B) : Int
Returns the index of the first occurence of the specified object in this iterable object.
Notes
may not terminate for infinite-sized collections.
Parameters
elem - element to search for.
Returns
the index in this sequence of the first occurence of the specified element, or -1 if the sequence does not contain this element.
def foldLeft[B](z : B)(op : (B, A) => B) : B
Combines the elements of this iterator together using the binary operator op, from left to right, and starting with the value z.
Returns
op(... (op(op(z,a0),a1) ...), an) if the iterator yields elements a0, a1, ..., an.
def foldRight[B](z : B)(op : (A, B) => B) : B
Combines the elements of this iterator together using the binary operator op, from right to left, and starting with the value z.
Returns
a0 op (... op (an op z)...) if the iterator yields elements a0, a1, ..., an.
def /:[B](z : B)(op : (B, A) => B) : B
Similar to foldLeft but can be used as an operator with the order of iterator and zero arguments reversed. That is, z /: xs is the same as xs foldLeft z.
Parameters
z - the left argument of the first application of op (evaluation occurs from left to right).
op - the applied operator.
Returns
the result value
See Also
foldLeft.
def :\[B](z : B)(op : (A, B) => B) : B
An alias for foldRight. That is, xs :\ z is the same as xs foldRight z.
Parameters
z - the right argument of the first application of op (evaluation occurs from right to left).
op - the applied operator.
Returns
the result value.
See Also
foldRight.
def reduceLeft[B >: A](op : (B, A) => B) : B
Combines the elements of this iterator together using the binary operator op, from left to right
Parameters
op - The operator to apply
Returns
op(... op(a0,a1), ..., an) if the iterator yields elements a0, a1, ..., an.
Throws
Predef.UnsupportedOperationException - if the iterator is empty.
def reduceRight[B >: A](op : (A, B) => B) : B
Combines the elements of this iterator together using the binary operator op, from right to left
Parameters
op - The operator to apply
Returns
a0 op (... op (an-1 op an)...) if the iterator yields elements a0, a1, ..., an.
Throws
Predef.UnsupportedOperationException - if the iterator is empty.
def reduceLeftOpt[B >: A](op : (B, A) => B) : Option[B]
Combines the elements of this iterator together using the binary operator op, from left to right
Parameters
op - The operator to apply
Returns
If the iterable is non-empty, the result of the operations as an Option, otherwise None.
def reduceRightOpt[B >: A](op : (A, B) => B) : Option[B]
Combines the elements of this iterable object together using the binary operator op, from right to left.
Parameters
op - The operator to apply
Returns
If the iterable is non-empty, the result of the operations as an Option, otherwise None.
def buffered : BufferedIterator[A]
Returns a buffered iterator from this iterator.
def length : Int
Returns the number of elements in this iterator.
Notes
The iterator is at its end after this method returns.
def duplicate : (Iterator[A], Iterator[A])
Creates two new iterators that both iterate over the same elements as this iterator (in the same order).
Returns
a pair of iterators
def patch[B >: A](from : Int, patchElems : Iterator[B], replaced : Int) : Iterator[B]
Returns this iterator with patched values.
Parameters
from - The start index from which to patch
ps - The iterator of patch values
replaced - The number of values in the original iterator that are replaced by the patch.
def copyToArray[B >: A](xs : Array[B], start : Int, len : Int) : Unit
Fills the given array `xs` with at most `len` elements of this iterator starting at position `start` until either `len` elements have been copied, or the end of the iterator is reached, or the end of the array `xs` is reached.
Parameters
xs - the array to fill.
start - starting index.
len - number of elements to copy
def copyToArray[B >: A](xs : Array[B], start : Int) : Unit
Fills the given array xs with the elements of this iterator starting at position start until either the end of the current iterator or the end of array `xs` is reached.
Parameters
xs - the array to fill.
start - starting index.
def copyToArray[B >: A](xs : Array[B]) : Unit
Fills the given array xs with the elements of this iterator starting at position 0 until either the end of the current iterator or the end of array `xs` is reached.
Parameters
xs - the array to fill.
def copyToBuffer[B >: A](dest : Buffer[B]) : Unit
Copy all elements to a buffer
Parameters
dest - The buffer to which elements are copied
def toList : List[A]
Traverse this iterator and return all elements in a list.
Returns
A list which enumerates all elements of this iterator.
def toStream : Stream[A]
Traverse this iterator and return all elements in a stream.
Returns
A stream which enumerates all elements of this iterator.
def toSequence : Sequence[A]
Traverse this iterator and return all elements in a sequence.
Returns
A sequence which enumerates all elements of this iterator.
def mkString(start : java.lang.String, sep : java.lang.String, end : java.lang.String) : java.lang.String
Returns a string representation of the elements in this iterator. The resulting string begins with the string start and is finished by the string end. Inside, the string representations of elements (w.r.t. the method toString) are separated by the string sep.

Ex:
List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"

Parameters
start - starting string.
sep - separator string.
end - ending string.
Returns
a string representation of this iterable object.
def mkString(sep : java.lang.String) : java.lang.String
Returns a string representation of this iterable object. The string representations of elements (w.r.t. the method toString()) are separated by the string sep.
Parameters
sep - separator string.
Returns
a string representation of this iterable object.
def mkString : java.lang.String
Returns a string representation of this iterable object. The string representations of elements (w.r.t. the method toString()) are concatenated without any separator string.
Returns
a string representation of this iterable object.
def addString(buf : StringBuilder, start : java.lang.String, sep : java.lang.String, end : java.lang.String) : StringBuilder
Write all elements of this iterator into given string builder. The written text begins with the string start and is finished by the string end. Inside, the string representations of elements (w.r.t. the method toString()) are separated by the string sep.
def addString(buf : StringBuilder, sep : java.lang.String) : StringBuilder
Write all elements of this iterator into given string builder. The string representations of elements (w.r.t. the method toString()) are separated by the string sep.
def addString(buf : StringBuilder) : StringBuilder
Write all elements of this string into given string builder without using any separator between consecutive elements.
override def toString : java.lang.String
Returns a string representation of the object.

The default representation is platform dependent.

Returns
a string representation of the object.

@deprecated("use <code>++</code>")

def append[B >: A](that : Iterator[B]) : Iterator[B]
Returns a new iterator that first yields the elements of this iterator followed by the elements provided by iterator that.
@deprecated("use `indexWhere` instead")

def findIndexOf(p : (A) => Boolean) : Int
Returns index of the first element satisfying a predicate, or -1.
@deprecated("use toSequence instead")

def collect : Sequence[A]
Collect elements into a seq.
Returns
a sequence which enumerates all elements of this iterator.
@deprecated("use zipWithIndex in Iterator")

def counted : CountedIterator[A]
Returns a counted iterator from this iterator.
@deprecated("use copyToArray instead")

def readInto[B >: A](xs : Array[B], start : Int, sz : Int) : Unit
Fills the given array xs with the elements of this sequence starting at position start. Like copyToArray, but designed to accomodate IO stream operations.
Parameters
xs - the array to fill.
start - the starting index.
sz - the maximum number of elements to be read.
Precondition
the array must be large enough to hold sz elements.
@deprecated("use copyToArray instead")

def readInto[B >: A](xs : Array[B], start : Int) : Unit
@deprecated("use copyToArray instead")

def readInto[B >: A](xs : Array[B]) : Unit
Scala Library