scala
class List

[source: `scala/List.scala`]

`sealed abstract` `class` List[+A]
  `extends` Seq[A]

  A class representing an ordered collection of elements of type `a`. This class comes with two implementing case classes `scala.Nil` and `scala.::` that implement the abstract members `isEmpty`, `head` and `tail`.

Author
  Martin Odersky and others
Version
  1.0, 16/07/2003

Direct Known Subclasses:
  Nil, ::

Method Summary
`def` | :: [B >: A](x : B) : List[B] Add an element `x` at the beginning of this list.
`def` | ::: [B >: A](prefix : List[B]) : List[B] Returns a list resulting from the concatenation of the given list `prefix` and this list.
`def` | apply (n : Int) : A Returns the `n`-th element of this list. The first element (head of the list) is at position 0.
`def` | break (p : (A) => Boolean) : (List[A], List[A]) Like `span` but with the predicate inverted.
`def` | count (p : (A) => Boolean) : Int Count the number of elements in the list which satisfy a predicate.
`def` | diff [B >: A](that : List[B]) : List[B] Computes the difference between this list and the given list `that`.
`override def` | drop (n : Int) : List[A] Returns the list without its `n` first elements. If this list has less than `n` elements, the empty list is returned.
`def` | dropRight (n : Int) : List[A] Returns the list wihout its rightmost `n` elements.
`override def` | dropWhile (p : (A) => Boolean) : List[A] Returns the longest suffix of this list whose first element does not satisfy the predicate `p`.
`override def` | elements : Iterator[A] Returns the elements in the list as an iterator
`override def` | exists (p : (A) => Boolean) : Boolean Tests the existence in this list of an element that satisfies the predicate `p`.
`override final def` | filter (p : (A) => Boolean) : List[A] Returns all the elements of this list that satisfy the predicate `p`. The order of the elements is preserved. It is guarenteed that the receiver list itself is returned iff all its elements satisfy the predicate `p'. Hence the following equality is valid: (xs filter p) eq xs == xs forall p
`override def` | find (p : (A) => Boolean) : Option[A] Find and return the first element of the list satisfying a predicate, if any.
`override final def` | flatMap [B](f : (A) => Iterable[B]) : List[B] Applies the given function `f` to each element of this list, then concatenates the results.
`def` | flatten [B](`implicit` f : (A) => Iterable[B]) : List[B]
`override def` | foldLeft [B](z : B)(f : (B, A) => B) : B Combines the elements of this list 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 list together using the binary function `f`, from right 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 list.
`override final def` | foreach (f : (A) => Unit) : Unit Apply the given function `f` to each element of this list (while respecting the order of the elements).
`abstract def` | head : A Returns this first element of the list.
`def` | indices : List[Int] Creates a list with all indices in the list. This is equivalent to a call to `List.range(0, xs.length)`.
`def` | init : List[A] Returns the list without its last element.
`def` | intersect [B >: A](that : List[B]) : List[B] Computes the intersection between this list and the given list `that`.
`override abstract def` | isEmpty : Boolean Returns true if the list does not contain any elements.
`override def` | last : A Returns the last element of this list.
`def` | length : Int Returns the number of elements in the list.
`override def` | lengthCompare (l : Int) : Int returns length - l, without calling length
`override final def` | map [B](f : (A) => B) : List[B] Returns the list resulting from applying the given function `f` to each element of this list.
`override def` | partition (p : (A) => Boolean) : (List[A], List[A]) Partition the list in two sub-lists according to a predicate.
`override def` | projection : Stream[A] returns a projection that can be used to call non-strict `filter`, `map`, and `flatMap` methods that build projections of the collection.
`override def` | reduceLeft [B >: A](f : (B, B) => B) : B Combines the elements of this list together using the binary operator `op`, from left to right
`override def` | reduceRight [B >: A](f : (B, B) => B) : B Combines the elements of this list together using the binary operator `op`, from right to left
`def` | remove (p : (A) => Boolean) : List[A] Removes all elements of the list which satisfy the predicate `p`. This is like `filter` with the predicate inversed.
`def` | removeDuplicates : List[A] Removes redundant elements from the list. Uses the method `==` to decide if two elements are identical.
`override def` | reverse : List[A] A list consisting of all elements of this list in reverse order.
`def` | reverseMap [B](f : (A) => B) : List[B] Apply a function to all the elements of the list, and return the reversed list of results. This is equivalent to a call to `map` followed by a call to `reverse`, but more efficient.
`def` | reverse_::: [B >: A](prefix : List[B]) : List[B] Reverse the given prefix and append the current list to that. This function is equivalent to an application of `reverse` on the prefix followed by a call to `:::`, but more efficient (and tail recursive).
`override def` | slice (start : Int, end : Int) : List[A] Returns the list with elements belonging to the given index range.
`def` | sort (lt : (A, A) => Boolean) : List[A] Sort the list according to the comparison function `<(e1: a, e2: a) => Boolean`, which should be true iff `e1` is smaller than `e2`.
`def` | span (p : (A) => Boolean) : (List[A], List[A]) Returns the longest prefix of the list whose elements all satisfy the given predicate, and the rest of the list.
`def` | splitAt (n : Int) : (List[A], List[A]) Split the list at a given point and return the two parts thus created.
`protected override def` | stringPrefix : java.lang.String Defines the prefix of this object's `toString` representation.
`abstract def` | tail : List[A] Returns this list without its first element.
`override def` | take (n : Int) : List[A] Returns the `n` first elements of this list, or else the whole list, if it has less than `n` elements.
`def` | takeRight (n : Int) : List[A] Returns the rightmost `n` elements from this list.
`override def` | takeWhile (p : (A) => Boolean) : List[A] Returns the longest prefix of this list whose elements satisfy the predicate `p`.
`override def` | toList : List[A] Overrides the method in Iterable for efficiency.
`override def` | toStream : Stream[A] Create a stream which contains all the elements of this iterable object.
`def` | union [B >: A](that : List[B]) : List[B] Computes the union of this list and the given list `that`.
`def` | zip [B](that : List[B]) : List[(A, B)] Returns a list formed from this list and the specified list `that` by associating each element of the former with the element at the same position in the latter. If one of the two lists is longer than the other, its remaining elements are ignored.
`def` | zipAll [B, C >: A, D >: B](that : List[B], thisElem : C, thatElem : D) : List[(C, D)] Returns a list formed from this list and the specified list `that` by associating each element of the former with the element at the same position in the latter.
`def` | zipWithIndex : List[(A, Int)] Returns a list that pairs each element of this list with its index, counting from 0.

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

Methods inherited from Collection
toString

Methods inherited from Iterable
findIndexOf, indexOf, /:, :\, copyToBuffer, sameElements, mkString, mkString, mkString, addString, addString, copyToArray, hasDefiniteSize

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

  Returns true if the list does not contain any elements.

Returns
  `true`, iff the list is empty.

Overrides
  Seq.isEmpty

`abstract` `def` head : A

  Returns this first element of the list.

Returns
  the first element of this list.
Throws
  Predef.NoSuchElementException - if the list is empty.

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

  returns length - l, without calling length

Overrides
  Seq.lengthCompare

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

  Returns this list without its first element.

Returns
  this list without its first element.
Throws
  Predef.NoSuchElementException - if the list is empty.

`` `def` ::[B >: A](x : B) : List[B]

  Add an element `x` at the beginning of this list.

Parameters
  `x -` the element to append.
Returns
  the list with `x` appended at the beginning.
Examples
  `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`

`` `def` :::[B >: A](prefix : List[B]) : List[B]

  Returns a list resulting from the concatenation of the given list `prefix` and this list.

Parameters
  `prefix -` the list to concatenate at the beginning of this list.
Returns
  the concatenation of the two lists.
Examples
  `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`

`` `def` reverse_:::[B >: A](prefix : List[B]) : List[B]

  Reverse the given prefix and append the current list to that. This function is equivalent to an application of `reverse` on the prefix followed by a call to `:::`, but more efficient (and tail recursive).

Parameters
  `prefix -` the prefix to reverse and then prepend
Returns
  the concatenation of the reversed prefix and the current list.

`` `def` length : Int

  Returns the number of elements in the list.

Returns
  the number of elements in the list.

Overrides
  Seq.length

`` `def` indices : List[Int]

  Creates a list with all indices in the list. This is equivalent to a call to `List.range(0, xs.length)`.

Returns
  a list of all indices in the list.

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

  Returns the elements in the list as an iterator

Returns
  an iterator on the list elements.

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

  Overrides the method in Iterable for efficiency.

Returns
  the list itself

`` `def` init : List[A]

  Returns the list without its last element.

Returns
  the list without its last element.
Throws
  Predef.UnsupportedOperationException - if the list is empty.

`override` `def` last : A

  Returns the last element of this list.

Returns
  the last element of the list.
Throws
  Predef.UnsupportedOperationException - if the list is empty.

Overrides
  Seq.last

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

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

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

Overrides
  Seq.take

`override` `def` slice(start : Int, end : Int) : List[A]

  Returns the list with elements belonging to the given index range.

Parameters
  `start -` the start position of the list slice.
  `end -` the end position (exclusive) of the list slice.
Returns
  the list with elements belonging to the given index range.

Overrides
  Seq.slice

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

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

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

Overrides
  Seq.drop

`` `def` takeRight(n : Int) : List[A]

  Returns the rightmost `n` elements from this list.

Parameters
  `n -` the number of elements to take
Returns
  the suffix of length `n` of the list

`` `def` dropRight(n : Int) : List[A]

  Returns the list wihout its rightmost `n` elements.

Parameters
  `n -` the number of elements to take
Returns
  the suffix of length `n` of the list

`` `def` splitAt(n : Int) : (List[A], List[A])

  Split the list at a given point and return the two parts thus created.

Parameters
  `n -` the position at which to split
Returns
  a pair of lists composed of the first `n` elements, and the other elements.

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

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

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

Overrides
  Seq.takeWhile

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

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

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

Overrides
  Seq.dropWhile

`` `def` span(p : (A) => Boolean) : (List[A], List[A])

  Returns the longest prefix of the list whose elements all satisfy the given predicate, and the rest of the list.

Parameters
  `p -` the test predicate
Returns
  a pair consisting of the longest prefix of the list whose elements all satisfy `p`, and the rest of the list.

`` `def` break(p : (A) => Boolean) : (List[A], List[A])

  Like `span` but with the predicate inverted.

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

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

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

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

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

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

Overrides
  Seq.map

`` `def` reverseMap[B](f : (A) => B) : List[B]

  Apply a function to all the elements of the list, and return the reversed list of results. This is equivalent to a call to `map` followed by a call to `reverse`, but more efficient.

Parameters
  `f -` the function to apply to each elements.
Returns
  the reversed list of results.

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

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

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

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

  Returns all the elements of this list that satisfy the predicate `p`. The order of the elements is preserved. It is guarenteed that the receiver list itself is returned iff all its elements satisfy the predicate `p'. Hence the following equality is valid: (xs filter p) eq xs == xs forall p

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

Overrides
  Seq.filter

`` `def` remove(p : (A) => Boolean) : List[A]

  Removes all elements of the list which satisfy the predicate `p`. This is like `filter` with the predicate inversed.

Parameters
  `p -` the predicate to use to test elements
Returns
  the list without all elements which satisfy `p`

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

  Partition the list in two sub-lists according to a predicate.

Parameters
  `p -` the predicate on which to partition
Returns
  a pair of lists: the list of all elements which satisfy `p` and the list of all elements which do not. The relative order of the elements in the sub-lists is the same as in the original list.

`` `def` sort(lt : (A, A) => Boolean) : List[A]

  Sort the list according to the comparison function `<(e1: a, e2: a) => Boolean`, which should be true iff `e1` is smaller than `e2`.

Parameters
  `lt -` the comparison function
Returns
  a list sorted according to the comparison function `<(e1: a, e2: a) => Boolean`.
Examples

            List("Steve", "Tom", "John", "Bob")
              .sort((e1, e2) => (e1 compareTo e2) < 0) =
            List("Bob", "John", "Steve", "Tom")

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

  Count the number of elements in the list which satisfy a predicate.

Parameters
  `p -` the predicate for which to count
Returns
  the number of elements satisfying the predicate `p`.

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

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

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

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

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

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

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

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

Parameters
  `p -` the predicate
Returns
  the first element in the list satisfying `p`, or `None` if none exists.

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

  Combines the elements of this list 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 list is `[a0, a1, ..., an]`.

`override` `def` foldRight[B](z : B)(f : (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`.

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

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

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

Parameters
  `op -` The operator to apply
Returns
  `op(... op(a0,a1), ..., an)` if the list has elements `a0, a1, ..., an`.
Throws
  Predef.UnsupportedOperationException - if the list is empty.

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

  Combines the elements of this list 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 list has elements `a0, a1, ..., an`.
Throws
  Predef.UnsupportedOperationException - if the list is empty.

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

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

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

Overrides
  Seq.flatMap

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

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

Overrides
  Seq.reverse

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

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

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

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

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

Returns
  the list `List((a0,0), (a1,1), ...)` where `ai` are the elements of this list.

`` `def` zipAll[B, C >: A, D >: B](that : List[B], thisElem : C, thatElem : D) : List[(C, D)]

  Returns a list formed from this list and the specified list `that` by associating each element of the former with the element at the same position in the latter.

Parameters
  `that -` list `that` may have a different length as the self list.
  `thisElem -` element `thisElem` is used to fill up the resulting list if the self list is shorter than `that`
  `thatElem -` element `thatElem` is used to fill up the resulting list if `that` is shorter than the self list
Returns
  `List((a0,b0), ..., (an,bn), (elem,bn+1), ..., {elem,bm})` when `[a0, ..., an] zip [b0, ..., bm]` is invoked where `m > n`.

`` `def` union[B >: A](that : List[B]) : List[B]

  Computes the union of this list and the given list `that`.

Parameters
  `that -` the list of elements to add to the list.
Returns
  a list without doubles containing the elements of this list and those of the given list `that`.

`` `def` diff[B >: A](that : List[B]) : List[B]

  Computes the difference between this list and the given list `that`.

Parameters
  `that -` the list of elements to remove from this list.
Returns
  this list without the elements of the given list `that`.

`` `def` flatten[B](`implicit` f : (A) => Iterable[B]) : List[B]

`` `def` intersect[B >: A](that : List[B]) : List[B]

  Computes the intersection between this list and the given list `that`.

Parameters
  `that -` the list to intersect.
Returns
  the list of elements contained both in this list and in the given list `that`.

`` `def` removeDuplicates : List[A]

  Removes redundant elements from the list. Uses the method `==` to decide if two elements are identical.

Returns
  the list without doubles.

`protected override` `def` stringPrefix : java.lang.String

  Defines the prefix of this object's `toString` representation.

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

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

Overrides
  Seq.projection

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

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

Notes
  consider using `projection` for lazy behavior.