scala

trait Iterator

[source: scala/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
1.2, 15/03/2004
Direct Known Subclasses:
BufferedIterator, CountedIterator, MutableIterator, Source, CharInputStreamIterator, SimpleTokenizer, XMLEventReader

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, start : String, sep : String, end : String) : StringBuilder
Write all elements of this string into given string builder.
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 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 sequence starting at position start.
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]
Removes the first n elements from this 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.
def duplicate : (Iterator[A], Iterator[A])
Creates two new iterators that both iterate over the same elements than 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 element of the iterable object satisfying a predicate, if any.
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 (f : (A) => Unit) : Unit
Apply a function f to all elements of this iterable object.
abstract def hasNext : Boolean
Does this iterator provide another element?
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 : String) : 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 (start : String, sep : String, end : String) : 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.
def readInto [B >: A](xs : Array[B], start : Int) : Unit
def readInto [B >: A](xs : Array[B]) : Unit
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 reduceLeft [B >: A](op : (B, B) => B) : B
Combines the elements of this iterator together using the binary operator op, from left to right
def reduceRight [B >: A](op : (B, B) => B) : B
Combines the elements of this iterator together using the binary operator op, from right to left
def take (n : Int) : Iterator[A]
Returns a new iterator that iterates only over the first n elements.
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]
Transform this iterator into a list of all elements.
override def toString : String
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 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
Class Summary
protected class PredicatedIterator (p : (A) => Boolean) extends DefaultBufferedIterator[A]
protected class TakeWhileIterator (p : (A) => Boolean) extends PredicatedIterator
Method Details
abstract def hasNext : Boolean
Does this iterator provide another element?

abstract def next : A
Returns the next element.

def take(n : Int) : Iterator[A]
Returns a new iterator that iterates only over the first n elements.
Parameters
n - the number of elements to take
Returns
the new iterator

def drop(n : Int) : Iterator[A]
Removes the first n elements from this iterator.
Parameters
n - the number of elements to drop
Returns
the new 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 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 ++

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 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.
Returns
an iterator yielding {a0,b0}, {a1,b1}, ... where ai are the elements from this iterator and bi are the elements from iterator that.

def zipWithIndex : Iterator[(A, Int)]
Return an iterator that pairs each element of this iterator with its index, counting from 0.
Parameters
start - the index of the first element.
Returns
an iterator yielding {a0,0}, {a1,1}... where ai are the elements from this iterator.

def foreach(f : (A) => Unit) : Unit
Apply a function f to all elements of this iterable object.
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.
Returns
true iff there is an element of this iterator which is equal (w.r.t. ==) to elem.

def find(p : (A) => Boolean) : Option[A]
Find and return the first element of the iterable object 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 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, B) => 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 : (B, 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 buffered : BufferedIterator[A]
Returns a buffered iterator from this iterator.

def counted : CountedIterator[A]
Returns a counted iterator from this iterator.

def duplicate : (Iterator[A], Iterator[A])
Creates two new iterators that both iterate over the same elements than this iterator (in the same order).
Returns
a pair of iterators

def copyToArray[B >: A](xs : Array[B], start : Int) : Unit
Fills the given array xs with the elements of this sequence starting at position start.
Parameters
xs - the array to fill.
start - the starting index.
Precondition
the array must be large enough to hold all elements.

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.

def readInto[B >: A](xs : Array[B], start : Int) : Unit

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

def copyToBuffer[B >: A](dest : Buffer[B]) : Unit
Copy all elements to a buffer
Parameters
The - buffer to which elements are copied
Returns
The buffer to which elements are copied

def toList : List[A]
Transform this iterator into a list of all elements.
Returns
a list which enumerates all elements of this iterator.

def mkString(start : String, sep : String, end : String) : 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 : String) : 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 addString(buf : StringBuilder, start : String, sep : String, end : String) : StringBuilder
Write all elements of this string into given string builder.
Parameters
buf - ...
start - the starting string
sep - the separator string
end - the ending string
Returns
...

override def toString : String