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