scala
trait Stream

[source: `scala/Stream.scala`]

`` `trait` Stream[+A]
  `extends` Projection[A]

  The class `Stream` implements lazy lists where elements are only evaluated when they are needed. Here is an example:

       object Main extends Application {

         def from(n: Int): Stream[Int] =
           Stream.cons(n, from(n + 1))

         def sieve(s: Stream[Int]): Stream[Int] =
           Stream.cons(s.head, sieve(s.tail filter { _ % s.head != 0 }))

         def primes = sieve(from(2))

         primes take 10 print
       }

Author
  Martin Odersky, Matthias Zenger
Version
  1.1 08/08/03

Direct Known Subclasses:
  Stream.Definite

Method Summary
`protected abstract def` | addDefinedElems (buf : StringBuilder, prefix : java.lang.String) : StringBuilder Write all elements of this string into given string builder
`override def` | append [B >: A](rest : => Iterable[B]) : Stream[B] The stream resulting from the concatenation of this stream with the argument stream.
`override def` | apply (n : Int) : A Returns the `n`-th element of this stream. The first element (head of the stream) is at position 0.
`override def` | copyToArray [B >: A](xs : Array[B], start : Int) : Unit Fills the given array `xs` with the elements of this stream starting at position `start`.
`override def` | drop (n : Int) : Stream[A] Returns the stream without its `n` first elements. If the stream has less than `n` elements, the empty stream is returned.
`override def` | dropWhile (p : (A) => Boolean) : Stream[A] Returns the longest suffix of this stream whose first element does not satisfy the predicate `p`.
`override def` | elements : Iterator[A] An iterator returning the elements of this stream one by one.
`override def` | exists (p : (A) => Boolean) : Boolean Tests the existence in this stream of an element that satisfies the predicate `p`.
`override def` | filter (p : (A) => Boolean) : Stream[A] Returns all the elements of this stream that satisfy the predicate `p`. The order of the elements is preserved.
`override def` | flatMap [B](f : (A) => Iterable[B]) : Stream[B] Applies the given function `f` to each element of this stream, then concatenates the results.
`override def` | foldLeft [B](z : B)(f : (B, A) => B) : B Combines the elements of this stream together using the binary function `f`, from left to right, and starting with the value `z`.
`override def` | foldRight [B](z : B)(f : (A, B) => B) : B Combines the elements of this stream together using the binary function `f`, from rigth to left, and starting with the value `z`.
`override def` | forall (p : (A) => Boolean) : Boolean Tests if the predicate `p` is satisfied by all elements in this stream.
`override def` | force : List[A] convert to a copied strict collection
`override def` | foreach (f : (A) => Unit) : Unit Apply the given function `f` to each element of this stream (while respecting the order of the elements).
`override 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.
`abstract def` | head : A The first element of this stream
`def` | init : Stream[A] The stream without its last element.
`override abstract def` | isEmpty : Boolean is this stream empty?
`override def` | last : A Returns the last element of this stream.
`override def` | length : Int The length of this stream
`override def` | lengthCompare (l : Int) : Int returns length - l without calling length
`override def` | map [B](f : (A) => B) : Stream[B] Returns the stream resulting from applying the given function `f` to each element of this stream.
`def` | print (sep : java.lang.String) : Unit Prints elements of this stream one by one, separated by `sep`
`def` | print : Unit Prints elements of this stream one by one, separated by commas
`override def` | reverse : Stream[A] A stream consisting of all elements of this stream in reverse order.
`abstract def` | tail : Stream[A] A stream consisting of the remaining elements of this stream after the first one.
`override def` | take (n : Int) : Stream[A] Returns the `n` first elements of this stream, or else the whole stream, if it has less than `n` elements.
`override def` | takeWhile (p : (A) => Boolean) : Stream[A] Returns the longest prefix of this stream whose elements satisfy the predicate `p`.
`override def` | toStream : Stream[A] Create a stream which contains all the elements of this iterable object.
`override def` | toString : java.lang.String Converts stream to string
`def` | zip [B](that : Stream[B]) : Stream[(A, B)] Returns a stream formed from this stream and the specified stream `that` by associating each element of the former with the element at the same position in the latter. If one of the two streams is longer than the other, its remaining elements are ignored.
`def` | zipWithIndex : Stream[(A, Int)] Returns a stream that pairs each element of this stream with its index, counting from 0.

Methods inherited from Projection
projection

Methods inherited from Seq
size, concat, lastOption, headOption, ++, isDefinedAt, lastIndexOf, slice, contains, subseq, toArray, equalsWith, startsWith, endsWith, indexOf, containsSlice

Methods inherited from Collection
stringPrefix

Methods inherited from Iterable
partition, find, findIndexOf, indexOf, /:, :\, reduceLeft, reduceRight, copyToBuffer, sameElements, toList, mkString, mkString, mkString, addString, addString

Methods inherited from PartialFunction
orElse, andThen

Methods inherited from Function1
compose

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

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

Method Details

`override abstract` `def` isEmpty : Boolean

  is this stream empty?

`override` `def` force : List[A]

  convert to a copied strict collection

Overrides
  Projection.force

`abstract` `def` head : A

  The first element of this stream

Throws
  Predef.NoSuchElementException - if the stream is empty.

`abstract` `def` tail : Stream[A]

  A stream consisting of the remaining elements of this stream after the first one.

Throws
  Predef.UnsupportedOperationException - if the stream is empty.

`override` `def` length : Int

  The length of this stream

`override` `def` lengthCompare(l : Int) : Int

  returns length - l without calling length

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

`override` `def` append[B >: A](rest : => Iterable[B]) : Stream[B]

  The stream resulting from the concatenation of this stream with the argument stream.

Parameters
  `rest -` The stream that gets appended to this stream

Overrides
  Projection.append

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

  An iterator returning the elements of this stream one by one.

`` `def` init : Stream[A]

  The stream without its last element.

Throws
  Predef.UnsupportedOperationException - if the stream is empty.

`override` `def` last : A

  Returns the last element of this stream.

Returns
  the last element of the stream.
Throws
  Predef.NoSuchElementException - if the stream is empty.

`override` `def` apply(n : Int) : A

  Returns the `n`-th element of this stream. The first element (head of the stream) is at position 0.

Parameters
  `n -` index of the element to return
Returns
  the element at position `n` in this stream.
Throws
  Predef.NoSuchElementException - if the stream is too short.

`override` `def` take(n : Int) : Stream[A]

  Returns the `n` first elements of this stream, or else the whole stream, if it has less than `n` elements.

Parameters
  `n -` the number of elements to take.
Returns
  the `n` first elements of this stream.

`override` `def` drop(n : Int) : Stream[A]

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

Parameters
  `n -` the number of elements to drop.
Returns
  the stream without its `n` first elements.

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

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

Parameters
  `p -` the test predicate.
Returns
  the longest prefix of this stream whose elements satisfy the predicate `p`.

Overrides
  Projection.takeWhile

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

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

Parameters
  `p -` the test predicate.
Returns
  the longest suffix of the stream whose first element does not satisfy the predicate `p`.

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

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

Parameters
  `f -` function to apply to each element.
Returns
  `[f(a0), ..., f(an)]` if this stream is `[a0, ..., an]`.

Overrides
  Projection.map

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

  Apply the given function `f` to each element of this stream (while respecting the order of the elements).

Parameters
  `f -` the treatment to apply to each element.

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

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

Parameters
  `p -` the predicate used to filter the stream.
Returns
  the elements of this stream satisfying `p`.

Overrides
  Projection.filter

`override` `def` forall(p : (A) => Boolean) : Boolean

  Tests if the predicate `p` is satisfied by all elements in this stream.

Parameters
  `p -` the test predicate.
Returns
  `true` iff all elements of this stream satisfy the predicate `p`.

`override` `def` exists(p : (A) => Boolean) : Boolean

  Tests the existence in this stream of an element that satisfies the predicate `p`.

Parameters
  `p -` the test predicate.
Returns
  `true` iff there exists an element in this stream that satisfies the predicate `p`.

`override` `def` foldLeft[B](z : B)(f : (B, A) => B) : B

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

Returns
  `f(... (f(f(z, a0), a1) ...), an)` if the stream is `[a0, a1, ..., an]`.

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

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

Returns
  `f(a0, f(a1, f(..., f(an, z)...)))` if the stream is `[a0, a1, ..., an]`.

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

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

Parameters
  `f -` the function to apply on each element.
Returns
  `f(a0) ::: ... ::: f(an)` if this stream is `[a0, ..., an]`.

Overrides
  Projection.flatMap

`override` `def` toStream : Stream[A]

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

Notes
  consider using `projection` for lazy behavior.

`override` `def` reverse : Stream[A]

  A stream consisting of all elements of this stream in reverse order.

`override` `def` copyToArray[B >: A](xs : Array[B], start : Int) : Unit

  Fills the given array `xs` with the elements of this stream starting at position `start`.

Parameters
  `xs -` the array to fill.
  `start -` starting index.
Precondition
  the array must be large enough to hold all elements.

`` `def` zip[B](that : Stream[B]) : Stream[(A, B)]

  Returns a stream formed from this stream and the specified stream `that` by associating each element of the former with the element at the same position in the latter. If one of the two streams is longer than the other, its remaining elements are ignored.

Returns
  `Stream({a0,b0}, ..., {amin(m,n),bmin(m,n))}` when `Stream(a0, ..., am) zip Stream(b0, ..., bn)` is invoked.

`` `def` zipWithIndex : Stream[(A, Int)]

  Returns a stream that pairs each element of this stream with its index, counting from 0.

Returns
  the stream `Stream({a0,0}, {a0,1},...)` where `ai` are the elements of this stream.

`` `def` print : Unit

  Prints elements of this stream one by one, separated by commas

`` `def` print(sep : java.lang.String) : Unit

  Prints elements of this stream one by one, separated by `sep`

Parameters
  `sep -` The separator string printed between consecutive elements.

`override` `def` toString : java.lang.String

  Converts stream to string

`protected abstract` `def` addDefinedElems(buf : StringBuilder, prefix : java.lang.String) : StringBuilder

  Write all elements of this string into given string builder