 # Iterator

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

1. AnyRef
2. Any

### Type Members

1. #### class GroupedIterator[B >: A] extends Iterator[Seq[B]]

A flexible iterator for transforming an `Iterator[A]` into an Iterator[Seq[A]], with configurable sequence size, step, and strategy for dealing with elements which don't fit evenly

### Value Members

1. #### def ++[B >: A](that: ⇒ Iterator[B]): Iterator[B]

Concatenates this iterator with another

Concatenates this iterator with another.

2. #### def /:[B](z: B)(op: (B, A) ⇒ B): B

Applies a binary operator to a start value and all values produced by this iterator, going left to right

Applies a binary operator to a start value and all values produced by this iterator, going left to right.

Note: `/:` is alternate syntax for `foldLeft`; `z /: it` is the same as `it foldLeft z`.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

z

the start value.

op

the binary operator.

returns

the result of inserting `op` between consecutive values produced by this iterator going left to right with the start value `z` on the left: {{{ op(...op(z, x1), x2, ..., xn) }}} where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.

3. #### def :\[B](z: B)(op: (A, B) ⇒ B): B

Applies a binary operator to all values produced by this iterator and a start value, going right to left

Applies a binary operator to all values produced by this iterator and a start value, going right to left. Note: `:\` is alternate syntax for `foldRight`; `it :\ z` is the same as `it foldRight z`.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

z

the start value.

op

the binary operator.

returns

the result of inserting `op` between consecutive values produced by this iterator going right to left with the start value `z` on the right: {{{ op(x1, op(x2, ... op(xn, z)...)) }}} where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.

4. #### def addString(buf: StringBuilder): StringBuilder

Appends all values produced by this iterator to a string builder

Appends all values produced by this iterator to a string builder. The written text consists of the string representations (w.r.t. the method `toString`) of all values produced by this iterator without any separator string.

5. #### def addString(buf: StringBuilder, sep: String): StringBuilder

Appends all values produced by this iterator to a string builder using a separator string

Appends all values produced by this iterator to a string builder using a separator string. The written text consists of the string representations (w.r.t. the method `toString`) of all values produced by this iterator, separated by the string `sep`.

sep

the separator string.

returns

the string builder `b` to which elements were appended.

6. #### def addString(buf: StringBuilder, start: String, sep: String, end: String): StringBuilder

Appends all values produced by this iterator to a string builder using start, end, and separator strings

Appends all values produced by this iterator to a string builder using start, end, and separator strings. The written text begins with the string `start` and ends with the string `end`. Inside, the string representations (w.r.t. the method `toString`) of all values produced by this iterator are separated by the string `sep`.

start

the starting string.

sep

the separator string.

end

the ending string.

returns

the string builder `b` to which elements were appended.

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

Returns a new iterator that first yields the elements of this iterator followed by the elements provided by iterator `that`.

8. #### def buffered: BufferedIterator[A]

Creates a buffered iterator from this iterator

Creates a buffered iterator from this iterator.

9. #### def collect: Seq[A]

Collect elements into a seq

Collect elements into a seq.

10. #### def contains(elem: Any): Boolean

Tests whether this iterator contains a given value as an element

Tests whether this iterator contains a given value as an element.

Note: may not terminate for infinite iterators.

elem

the element to test.

returns

`true` if this iterator produces some value that is is equal (wrt `==`) to `elem`, `false` otherwise.

11. #### def copyToArray[B >: A](xs: Array[B]): Unit

Copies values produced by this iterator to an array

Copies values produced by this iterator to an array. Fills the given array `xs` with values produced by this iterator. Copying will stop once either the end of the current iterator is reached, or the end of the array is reached.

Note: will not terminate for infinite iterators.

B

the type of the elements of the array.

xs

the array to fill.

12. #### def copyToArray[B >: A](xs: Array[B], start: Int): Unit

Copies values produced by this iterator to an array

Copies values produced by this iterator to an array. Fills the given array `xs` with values produced by this iterator, after skipping `start` values. Copying will stop once either the end of the current iterator is reached, or the end of the array is reached.

Note: will not terminate for infinite iterators.

B

the type of the elements of the array.

xs

the array to fill.

start

the starting index.

13. #### def copyToArray[B >: A](xs: Array[B], start: Int, len: Int): Unit

Copies selected values produced by this iterator to an array

Copies selected values produced by this iterator to an array. Fills the given array `xs` with at most `len` values produced by this iterator, after skipping `start` values. Copying will stop once either the end of the current iterator is reached, or the end of the array is reached, or `len` elements have been copied.

Note: will not terminate for infinite iterators.

B

the type of the elements of the array.

xs

the array to fill.

start

the starting index.

len

the maximal number of elements to copy.

14. #### def copyToBuffer[B >: A](dest: Buffer[B]): Unit

Copies all values produced by this iterator to a buffer

Copies all values produced by this iterator to a buffer.

Note: will not terminate for infinite iterators.

dest

The buffer to which elements are copied

15. #### def counted: CountedIterator[A]

Returns a counted iterator from this iterator

Returns a counted iterator from this iterator.

16. #### def drop(n: Int): Iterator[A]

Advances this iterator past the first n elements, or the length of the iterator, whichever is smaller

Advances this iterator past the first n elements, or the length of the iterator, whichever is smaller.

n

the number of elements to drop

returns

an iterator which produces all values of the current iterator, except it omits the first `n` values.

17. #### 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

Skips longest sequence of elements of this iterator which satisfy given predicate `p`, and returns an iterator of the remaining elements.

p

the predicate used to skip elements.

returns

an iterator consisting of the remaining elements

18. #### def duplicate: (Iterator[A], Iterator[A])

Creates two new iterators that both iterate over the same elements as this iterator (in the same order)

Creates two new iterators that both iterate over the same elements as this iterator (in the same order).

19. #### def equals(arg0: Any): Boolean

This method is used to compare the receiver object (`this`) with the argument object (`arg0`) for equivalence

This method is used to compare the receiver object (`this`) with the argument object (`arg0`) for equivalence.

The default implementations of this method is an equivalence relation:

• It is reflexive: for any instance `x` of type `Any`, `x.equals(x)` should return `true`.
• It is symmetric: for any instances `x` and `y` of type `Any`, `x.equals(y)` should return `true` if and only if `y.equals(x)` returns `true`.
• It is transitive: for any instances `x`, `y`, and `z` of type `AnyRef` if `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`.

If you override this method, you should verify that your implementation remains an equivalence relation. Additionally, when overriding this method it is often necessary to override `hashCode` to ensure that objects that are "equal" (`o1.equals(o2)` returns `true`) hash to the same `Int` (`o1.hashCode.equals(o2.hashCode)`).

arg0

the object to compare against this object for equality.

returns

`true` if the receiver object is equivalent to the argument; `false` otherwise.

definition classes: AnyRef ⇐ Any
20. #### def exists(p: (A) ⇒ Boolean): Boolean

Tests whether a predicate holds for some of the values produced by this iterator

Tests whether a predicate holds for some of the values produced by this iterator.

Note: may not terminate for infinite iterators.

p

the predicate used to test elements.

returns

`true` if the given predicate `p` holds for some of the values produced by this iterator, otherwise `false`.

21. #### def filter(p: (A) ⇒ Boolean): Iterator[A]

Returns an iterator over all the elements of this iterator that satisfy the predicate `p`

Returns an iterator over all the elements of this iterator that satisfy the predicate `p`. The order of the elements is preserved.

p

the predicate used to test values.

returns

an iterator which produces those values of this iterator which satisfy the predicate `p`.

22. #### def filterNot(p: (A) ⇒ Boolean): Iterator[A]

Creates an iterator over all the elements of this iterator which do not satisfy a predicate p

Creates an iterator over all the elements of this iterator which do not satisfy a predicate p.

p

the predicate used to test values.

returns

an iterator which produces those values of this iterator which do not satisfy the predicate `p`.

23. #### def find(p: (A) ⇒ Boolean): Option[A]

Finds the first value produced by the iterator satisfying a predicate, if any

Finds the first value produced by the iterator satisfying a predicate, if any.

Note: may not terminate for infinite iterators.

p

the predicate used to test values.

returns

an option value containing the first value produced by the iterator that satisfies predicate `p`, or `None` if none exists.

24. #### def findIndexOf(p: (A) ⇒ Boolean): Int

Returns index of the first element satisfying a predicate, or -1

Returns index of the first element satisfying a predicate, or -1.

25. #### def flatMap[B](f: (A) ⇒ Iterator[B]): Iterator[B]

Creates a new iterator by applying a function to all values produced by this iterator and concatenating the results

Creates a new iterator by applying a function to all values produced by this iterator and concatenating the results.

f

the function to apply on each element.

returns

the iterator resulting from applying the given iterator-valued function `f` to each value produced by this iterator and concatenating the results.

26. #### def foldLeft[B](z: B)(op: (B, A) ⇒ B): B

Applies a binary operator to a start value and all values produced by this iterator, going left to right

Applies a binary operator to a start value and all values produced by this iterator, going left to right.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

z

the start value.

op

the binary operator.

returns

the result of inserting `op` between consecutive values produced by this iterator going left to right with the start value `z` on the left: {{{ op(...op(z, x1), x2, ..., xn) }}} where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.

27. #### def foldRight[B](z: B)(op: (A, B) ⇒ B): B

Applies a binary operator to all values produced by this iterator and a start value, going right to left

Applies a binary operator to all values produced by this iterator and a start value, going right to left.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

z

the start value.

op

the binary operator.

returns

the result of inserting `op` between consecutive values produced by this iterator going right to left with the start value `z` on the right: {{{ op(x1, op(x2, ... op(xn, z)...)) }}} where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.

28. #### def forall(p: (A) ⇒ Boolean): Boolean

Tests whether a predicate holds for all values produced by this iterator

Tests whether a predicate holds for all values produced by this iterator.

Note: may not terminate for infinite iterators.

p

the predicate used to test elements.

returns

`true` if the given predicate `p` holds for all values produced by this iterator, otherwise `false`.

29. #### def foreach[U](f: (A) ⇒ U): Unit

Applies a function `f` to all values produced by this iterator

Applies a function `f` to all values produced by this iterator.

U

the type parameter describing the result of function `f`. This result will always be ignored. Typically `U` is `Unit`, but this is not necessary.

f

the function that is applied for its side-effect to every element. The result of function `f` is discarded.

30. #### def grouped[B >: A](size: Int): GroupedIterator[B]

Returns an iterator which groups this iterator into fixed size blocks

Returns an iterator which groups this iterator into fixed size blocks. Example usages:

```   // Returns List(List(1, 2, 3), List(4, 5, 6), List(7)))
(1 to 7).iterator grouped 3 toList
// Returns List(List(1, 2, 3), List(4, 5, 6))
(1 to 7).iterator grouped 3 withPartial false toList
// Returns List(List(1, 2, 3), List(4, 5, 6), List(7, 20, 25)
// Illustrating that withPadding's argument is by-name.
val it2 = Iterator.iterate(20)(_ + 5)
(1 to 7).iterator grouped 3 withPadding it2.next toList
```

31. #### def hasNext: Boolean

Tests whether this iterator can provide another element

Tests whether this iterator can provide another element.

attributes: abstract
32. #### def hashCode(): Int

Returns a hash code value for the object

Returns a hash code value for the object.

The default hashing algorithm is platform dependent.

Note that it is allowed for two objects to have identical hash codes (`o1.hashCode.equals(o2.hashCode)`) yet not be equal (`o1.equals(o2)` returns `false`). A degenerate implementation could always return `0`. However, it is required that if two objects are equal (`o1.equals(o2)` returns `true`) that they have identical hash codes (`o1.hashCode.equals(o2.hashCode)`). Therefore, when overriding this method, be sure to verify that the behavior is consistent with the `equals` method.

definition classes: AnyRef ⇐ Any
33. #### def indexOf[B >: A](elem: B): Int

Returns the index of the first occurence of the specified object in this iterable object

Returns the index of the first occurence of the specified object in this iterable object.

Note: may not terminate for infinite iterators.

elem

element to search for.

returns

the index of the first occurence of `elem` in the values produced by this iterator, or -1 if such an element does not exist until the end of the iterator is reached.

34. #### def indexWhere(p: (A) ⇒ Boolean): Int

Returns the index of the first produced value satisfying a predicate, or -1

Returns the index of the first produced value satisfying a predicate, or -1.

Note: may not terminate for infinite iterators.

p

the predicate to test values

returns

the index of the first produced value satisfying `p`, or -1 if such an element does not exist until the end of the iterator is reached.

35. #### def length: Int

Returns the number of elements in this iterator

Returns the number of elements in this iterator.

Note: will not terminate for infinite iterators.

Note: The iterator is at its end after this method returns.

36. #### def map[B](f: (A) ⇒ B): Iterator[B]

Creates a new iterator that maps all produced values of this iterator to new values using a transformation function

Creates a new iterator that maps all produced values of this iterator to new values using a transformation function.

f

the transformation function

returns

a new iterator which transformes every value produced by this iterator by applying the functon `f` to it.

37. #### def mkString: String

Displays all values produced by this iterator in a string

Displays all values produced by this iterator in a string.

38. #### def mkString(sep: String): String

Displays all values produced by this iterator in a string using a separator string

Displays all values produced by this iterator in a string using a separator string.

sep

the separator string.

returns

a string representation of this iterator. In the resulting string the string representations (w.r.t. the method `toString`) of all values produced by this iterator are separated by the string `sep`.

39. #### def mkString(start: String, sep: String, end: String): String

Displays all values produced by this iterator in a string using start, end, and separator strings

Displays all values produced by this iterator in a string using start, end, and separator strings.

start

the starting string.

sep

the separator string.

end

the ending string.

returns

a string representation of this iterator. The resulting string begins with the string `start` and ends with the string `end`. Inside, the string representations (w.r.t. the method `toString`) of all values produced by this iterator are separated by the string `sep`.

40. #### def next(): A

Produces the next element of this iterator

Produces the next element of this iterator.

attributes: abstract
41. #### def padTo[A1 >: A](len: Int, elem: A1): Iterator[A1]

Appends an element value to this iterator until a given target length is reached

Appends an element value to this iterator until a given target length is reached.

len

the target length

elem

the padding value

returns

a new iterator consisting of producing all values of this iterator, followed by the minimal number of occurrences of `elem` so that the number of produced values is at least `len`.

42. #### def partialMap[B](pf: PartialFunction[A, B]): Iterator[B]

Creates an iterator by transforming values produced by this iterator with a partial function, dropping those values for which the partial function is not defined

Creates an iterator by transforming values produced by this iterator with a partial function, dropping those values for which the partial function is not defined.

pf

the partial function which filters and maps the iterator.

returns

a new iterator which yields each value `x` produced by this iterator for which `pf` is defined the image `pf(x)`.

43. #### def partition(p: (A) ⇒ Boolean): (Iterator[A], Iterator[A])

Partitions this iterator in two iterators according to a predicate

Partitions this iterator in two iterators according to a predicate.

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.

44. #### def patch[B >: A](from: Int, patchElems: Iterator[B], replaced: Int): Iterator[B]

Returns this iterator with patched values

Returns this iterator with patched values.

from

The start index from which to patch

replaced

The number of values in the original iterator that are replaced by the patch.

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

Fills the given array `xs` with the elements of this sequence starting at position `start`. Like `copyToArray`, but designed to accomodate IO stream operations.

xs

the array to fill.

start

the starting index.

sz

the maximum number of elements to be read.

48. #### def reduceLeft[B >: A](op: (B, A) ⇒ B): B

Applies a binary operator to all values produced by this iterator, going left to right

Applies a binary operator to all values produced by this iterator, going left to right.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

op

the binary operator.

returns

the result of inserting `op` between consecutive values produced by this iterator going left to right: {{{ op(...(op(x1, x2), ... ) , xn) }}} where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.

49. #### def reduceLeftOption[B >: A](op: (B, A) ⇒ B): Option[B]

Optionally applies a binary operator to all values produced by this iterator, going left to right

Optionally applies a binary operator to all values produced by this iterator, going left to right.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

op

the binary operator.

returns

an option value containing the result of `reduceLeft(op)` is this iterator is nonempty, `None` otherwise.

50. #### def reduceRight[B >: A](op: (A, B) ⇒ B): B

Applies a binary operator to all values produced by this iterator, going right to left

Applies a binary operator to all values produced by this iterator, going right to left.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

op

the binary operator.

returns

the result of inserting `op` between consecutive values produced by this iterator going right to left: {{{ op(x1, op(x2, ..., op(xn-1, xn)...)) }}} where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.

51. #### def reduceRightOption[B >: A](op: (A, B) ⇒ B): Option[B]

Optionally applies a binary operator to all values produced by this iterator, going right to left

Optionally applies a binary operator to all values produced by this iterator, going right to left.

Note: will not terminate for infinite iterators.

B

the result type of the binary operator.

op

the binary operator.

returns

an option value containing the result of `reduceRight(op)` is this iterator is nonempty, `None` otherwise.

52. #### def sameElements(that: Iterator[_]): Boolean

Tests if another iterator produces the same valeus as this one

Tests if another iterator produces the same valeus as this one.

Note: will not terminate for infinite iterators.

that

the other iterator

returns

`true`, if both iterators produce the same elements in the same order, `false` otherwise.

53. #### def slice(from: Int, until: Int): Iterator[A]

Creates an iterator returning an interval of the values produced by this iterator

Creates an iterator returning an interval of the values produced by this iterator.

from

the index of the first element in this iterator which forms part of the slice.

until

the index of the first element following the slice.

returns

an iterator which advances this iterator past the first `from` elements using `drop`, and then takes `until - from` elements, using `take`.

54. #### def sliding[B >: A](size: Int, step: Int): GroupedIterator[B]

Returns an iterator which presents a "sliding window" view of another iterator

Returns an iterator which presents a "sliding window" view of another iterator. The first argument is the window size, and the second is how far to advance the window on each iteration; defaults to 1. Example usages:

```   // Returns List(List(1, 2, 3), List(2, 3, 4), List(3, 4, 5))
(1 to 5).iterator.sliding(3).toList
// Returns List(List(1, 2, 3, 4), List(4, 5))
(1 to 5).iterator.sliding(4, 3).toList
// Returns List(List(1, 2, 3, 4))
(1 to 5).iterator.sliding(4, 3).withPartial(false).toList
// Returns List(List(1, 2, 3, 4), List(4, 5, 20, 25))
// Illustrating that withPadding's argument is by-name.
val it2 = Iterator.iterate(20)(_ + 5)
(1 to 5).iterator.sliding(4, 3).withPadding(it2.next).toList
```

55. #### def take(n: Int): Iterator[A]

Selects first n values of this iterator

Selects first n values of this iterator.

n

the number of values to take

returns

an iterator producing only of the first `n` values of this iterator, or else the whole iterator, if it produces less than `n` values.

56. #### def takeWhile(p: (A) ⇒ Boolean): Iterator[A]

Takes longest prefix of values produced by this iterator that satisfy a predicate

Takes longest prefix of values produced by this iterator that satisfy a predicate.

p

The predicate used to test elements.

returns

An iterator returning the values produced by this iterator, until this iterator produces a value that does not satisfy the predicate `p`.

57. #### def toList: List[A]

Traverses this iterator and returns all produced values in a list

Traverses this iterator and returns all produced values in a list.

Note: will not terminate for infinite iterators.

58. #### def toSeq: Seq[A]

Traverses this iterator and returns all produced values in a sequence

Traverses this iterator and returns all produced values in a sequence.

Note: will not terminate for infinite iterators.

59. #### def toStream: Stream[A]

Traverses this iterator and returns all produced values in a list

Traverses this iterator and returns all produced values in a list.

60. #### def toString(): String

Converts this iterator to a string

Converts this iterator to a string.

61. #### def withFilter(p: (A) ⇒ Boolean): Iterator[A]

Creates an iterator over all the elements of this iterator that satisfy the predicate `p`

Creates an iterator over all the elements of this iterator that satisfy the predicate `p`. The order of the elements is preserved.

p

the predicate used to test values.

returns

an iterator which produces those values of this iterator which satisfy the predicate `p`.

62. #### def zip[B](that: Iterator[B]): Iterator[(A, B)]

Creates an iterator formed from this iterator and another iterator by combining corresponding values in pairs

Creates an iterator formed from this iterator and another iterator by combining corresponding values in pairs. If one of the two iterators is longer than the other, its remaining elements are ignored.

that

The iterator providing the second half of each result pair

returns

a new iterator containing pairs consisting of corresponding elements of this iterator and `that`. The number of elements returned by the new iterator is the minimum of the number of elements returned by this iterator and `that`.

63. #### def zipAll[B, A1 >: A, B1 >: B](that: Iterator[B], thisElem: A1, thatElem: B1): Iterator[(A1, B1)]

Creates an iterator formed from this iterator and another iterator by combining corresponding elements in pairs

Creates an iterator formed from this iterator and another iterator by combining corresponding elements in pairs. If one of the two iterators is shorter than the other, placeholder elements are used to extend the shorter iterator to the length of the longer.

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

a new iterator containing pairs consisting of corresponding values of this iterator and `that`. The length of the returned iterator is the maximum of the lengths of this iterator and `that`. If this iterator is shorter than `that`, `thisElem` values are used to pad the result. If `that` is shorter than this iterator, `thatElem` values are used to pad the result.

64. #### def zipWithIndex: Iterator[(A, Int)] {...}

Creates an iterator that pairs each element produced by this iterator with its index, counting from 0

Creates an iterator that pairs each element produced by this iterator with its index, counting from 0.