scala
trait Iterable

[source: `scala/Iterable.scala`]

`` `trait` Iterable[+A]
  `extends` AnyRef

  Collection classes mixing in this class provide a method `elements` which returns an iterator over all the elements contained in the collection.

Notes
  If a collection has a known `size`, it should also sub-type `Collection`. Only potentially unbounded collections should directly sub-class `Iterable`.
Author
  Matthias Zenger
Version
  1.1, 04/02/2004

Direct Known Subclasses:
  Relation, Collection, Iterable.Projection, IterableProxy, Ranged, Binders.Scope

Method Summary
`def` | ++ [B >: A](that : Iterable[B]) : Collection[B] Appends two iterable objects.
`def` | /: [B](z : B)(op : (B, A) => B) : B Similar to `foldLeft` but can be used as an operator with the order of list 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
`def` | addString (buf : StringBuilder, start : java.lang.String, sep : java.lang.String, end : java.lang.String) : StringBuilder Write all elements of this string into given string builder.
`def` | concat [B >: A](that : Iterable[B]) : Collection[B] Appends two iterable objects.
`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 given buffer
`def` | drop (n : Int) : Collection[A] Returns this iterable without its `n` first elements If this iterable has less than `n` elements, the empty iterable is returned.
`def` | dropWhile (p : (A) => Boolean) : Collection[A] Returns the longest suffix of this iterable whose first element does not satisfy the predicate `p`.
`abstract def` | elements : Iterator[A] Creates a new iterator over all elements contained in this object.
`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) : Iterable[A] Returns all the elements of this iterable 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` | findIndexOf (p : (A) => Boolean) : Int Returns index of the first element satisying a predicate, or -1.
`def` | flatMap [B](f : (A) => Iterable[B]) : Iterable[B] Applies the given function `f` to each element of this iterable, then concatenates the results.
`def` | foldLeft [B](z : B)(op : (B, A) => B) : B Combines the elements of this iterable object together using the binary function `f`, 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 list together using the binary function `f`, 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.
`def` | hasDefiniteSize : Boolean returns true iff this collection has a bound size. Many APIs in this trait will not work on collections of unbound sizes.
`def` | indexOf [B >: A](elem : B) : Int Returns the index of the first occurence of the specified object in this iterable object.
`def` | isEmpty : Boolean Is this collection empty?
`def` | map [B](f : (A) => B) : Iterable[B] Returns the iterable resulting from applying the given function `f` to each element of this iterable.
`def` | mkString : java.lang.String Converts a collection into a flat `String` by each element's toString method.
`def` | mkString (start : java.lang.String, sep : java.lang.String, end : java.lang.String) : java.lang.String Returns a string representation of this iterable object. 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`.
`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` | partition (p : (A) => Boolean) : (Iterable[A], Iterable[A]) Partitions this iterable in two iterables according to a predicate.
`def` | projection : Projection[A] returns a projection that can be used to call non-strict `filter`, `map`, and `flatMap` methods that build projections of the collection.
`def` | reduceLeft [B >: A](op : (B, B) => B) : B Combines the elements of this iterable object together using the binary operator `op`, from left to right
`def` | reduceRight [B >: A](op : (B, B) => B) : B Combines the elements of this iterable object together using the binary operator `op`, from right to left
`def` | sameElements [B >: A](that : Iterable[B]) : Boolean Checks if the other iterable object contains the same elements.
`def` | take (n : Int) : Collection[A] Returns an iterable consisting only over the first `n` elements of this iterable, or else the whole iterable, if it has less than `n` elements.
`def` | takeWhile (p : (A) => Boolean) : Iterable[A] Returns the longest prefix of this iterable whose elements satisfy the predicate `p`.
`def` | toList : List[A] Create a fresh list with all the elements of this iterable object.
`def` | toStream : Stream[A] Create a stream which contains all the elements of this iterable object.

Methods inherited from AnyRef
getClass, hashCode, equals, clone, toString, notify, notifyAll, wait, wait, wait, finalize, ==, !=, eq, ne, synchronized

Methods inherited from Any
==, !=, isInstanceOf, asInstanceOf

Method Details

`abstract` `def` elements : Iterator[A]

  Creates a new iterator over all elements contained in this object.

Returns
  the new iterator

@deprecated
`` `def` concat[B >: A](that : Iterable[B]) : Collection[B]

  Appends two iterable objects.

Returns
  the new iterable object
Deprecated
  use `++` instead
Notes
  Will not terminate for infinite-sized collections.

`` `def` ++[B >: A](that : Iterable[B]) : Collection[B]

  Appends two iterable objects.

Returns
  the new iterable object
Notes
  Will not terminate for infinite-sized collections.

`` `def` map[B](f : (A) => B) : Iterable[B]

  Returns the iterable resulting from applying the given function `f` to each element of this iterable.

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `f -` function to apply to each element.
Returns
  `f(a0), ..., f(an)` if this iterable is `a0, ..., an`.

`` `def` flatMap[B](f : (A) => Iterable[B]) : Iterable[B]

  Applies the given function `f` to each element of this iterable, then concatenates the results.

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `f -` the function to apply on each element.
Returns
  `f(a0) ::: ... ::: f(an)` if this iterable is `a0, ..., an`.

`` `def` filter(p : (A) => Boolean) : Iterable[A]

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

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `p -` the predicate used to filter the list.
Returns
  the elements of this list satisfying `p`.

`` `def` partition(p : (A) => Boolean) : (Iterable[A], Iterable[A])

  Partitions this iterable in two iterables according to a predicate.

Parameters
  `p -` the predicate on which to partition
Returns
  a pair of iterables: the iterable that satisfy the predicate `p` and the iterable that do not. The relative order of the elements in the resulting iterables is the same as in the original iterable.

`` `def` takeWhile(p : (A) => Boolean) : Iterable[A]

  Returns the longest prefix of this iterable whose elements satisfy the predicate `p`.

Notes
  May not terminate for infinite-sized collections.
Parameters
  `p -` the test predicate.
Returns
  the longest prefix of this iterable whose elements satisfy the predicate `p`.

`` `def` dropWhile(p : (A) => Boolean) : Collection[A]

  Returns the longest suffix of this iterable whose first element does not satisfy the predicate `p`.

Notes
  May not terminate for infinite-sized collections.
Parameters
  `p -` the test predicate.
Returns
  the longest suffix of the iterable whose first element does not satisfy the predicate `p`.

@deprecated
`` `def` take(n : Int) : Collection[A]

  Returns an iterable consisting only over the first `n` elements of this iterable, or else the whole iterable, if it has less than `n` elements.

Deprecated
  API does not make sense for non-ordered collections
Parameters
  `n -` the number of elements to take
Returns
  the new iterable

@deprecated
`` `def` drop(n : Int) : Collection[A]

  Returns this iterable without its `n` first elements If this iterable has less than `n` elements, the empty iterable is returned.

Notes
  Will not terminate for infinite-sized collections.
Deprecated
  API does not make sense for non-ordered collections
Parameters
  `n -` the number of elements to drop
Returns
  the new iterable

`` `def` foreach(f : (A) => Unit) : Unit

  Apply a function `f` to all elements of this iterable object.

Notes
  Will not terminate for infinite-sized collections.
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.

Notes
  May not terminate for infinite-sized collections.
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.

Notes
  May not terminate for infinite-sized collections.
Parameters
  `p -` the predicate
Returns
  true, iff the predicate yields true for at least one element.

`` `def` find(p : (A) => Boolean) : Option[A]

  Find and return the first element of the iterable object satisfying a predicate, if any.

Notes
  may not terminate for infinite-sized collections.
Parameters
  `p -` the predicate
Returns
  the first element in the iterable object satisfying `p`, or `None` if none exists.

`` `def` findIndexOf(p : (A) => Boolean) : Int

  Returns index of the first element satisying 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 iterable object together using the binary function `f`, from left to right, and starting with the value `z`.

Notes
  Will not terminate for infinite-sized collections.
Returns
  `f(... (f(f(z, a0), a1) ...), an)` if the list is `[a0, a1, ..., an]`.

`` `def` foldRight[B](z : B)(op : (A, B) => B) : B

  Combines the elements of this list together using the binary function `f`, from right to left, and starting with the value `z`.

Notes
  Will not terminate for infinite-sized collections.
Returns
  `f(a0, f(a1, f(..., f(an, z)...)))` if the list is `[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 list and zero arguments reversed. That is, `z /: xs` is the same as `xs foldLeft z`

Notes
  Will not terminate for infinite-sized collections.

`` `def` :\[B](z : B)(op : (A, B) => B) : B

  An alias for `foldRight`. That is, `xs :\ z` is the same as `xs foldRight z`

Notes
  Will not terminate for infinite-sized collections.

`` `def` reduceLeft[B >: A](op : (B, B) => B) : B

  Combines the elements of this iterable object together using the binary operator `op`, from left to right

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `op -` The operator to apply
Returns
  `op(... op(a0,a1), ..., an)` if the iterable object has elements `a0, a1, ..., an`.
Throws
  Predef.UnsupportedOperationException - if the iterable object is empty.

`` `def` reduceRight[B >: A](op : (B, B) => B) : B

  Combines the elements of this iterable object together using the binary operator `op`, from right to left

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `op -` The operator to apply
Returns
  `a0 op (... op (an-1 op an)...)` if the iterable object has elements `a0, a1, ..., an`.
Throws
  Predef.UnsupportedOperationException - if the iterator is empty.

`` `def` copyToBuffer[B >: A](dest : Buffer[B]) : Unit

  Copy all elements to a given buffer

Notes
  Will not terminate for infinite-sized collections.
  Will not terminate if not finite.
Parameters
  `dest -` The buffer to which elements are copied

`` `def` sameElements[B >: A](that : Iterable[B]) : Boolean

  Checks if the other iterable object contains the same elements.

Notes
  will not terminate for infinite-sized collections.
Parameters
  `that -` the other iterable object
Returns
  true, iff both iterable objects contain the same elements.

`` `def` toList : List[A]

  Create a fresh list with all the elements of this iterable object.

Notes
  Will not terminate for infinite-sized collections.

`` `def` toStream : Stream[A]

  Create a stream which contains all the elements of this iterable object.

Notes
  consider using `projection` for lazy behavior.

`` `def` mkString(start : java.lang.String, sep : java.lang.String, end : java.lang.String) : java.lang.String

  Returns a string representation of this iterable object. 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`.

Examples
  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
Notes
  Will not terminate for infinite-sized collections.
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`.

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `sep -` separator string.
Returns
  a string representation of this iterable object.

`` `def` mkString : java.lang.String

  Converts a collection into a flat `String` by each element's toString method.

Notes
  Will not terminate for infinite-sized collections.

`` `def` addString(buf : StringBuilder, start : java.lang.String, sep : java.lang.String, end : java.lang.String) : StringBuilder

  Write all elements of this string into given string builder.

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `buf -` ...
Returns
  ...

`` `def` addString(buf : StringBuilder, sep : java.lang.String) : StringBuilder

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

Notes
  Will not terminate for infinite-sized collections.
Parameters
  `xs -` the array to fill.
  `start -` starting index.
Precondition
  the array must be large enough to hold all elements.

`` `def` isEmpty : Boolean

  Is this collection empty?

`` `def` projection : Projection[A]

  returns a projection that can be used to call non-strict `filter`, `map`, and `flatMap` methods that build projections of the collection.

`` `def` hasDefiniteSize : Boolean

  returns true iff this collection has a bound size. Many APIs in this trait will not work on collections of unbound sizes.