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.