Learning Scala : Scala List API with sample code snippet

Authored by Win Myo Htet

We have gone through all the functions of List API and along the way we have skipped around to organize functions in a logical way, thus making it hard to remember which blog covers which function. To alleviate such navigation pain, here is the List API functions list with hyper link to the blog covering the function. If you have not known how to read the scaladoc, it is recommended that you go through the first few blogs where some of the stuff like implicit and lower bound are covered. The later blogs assumed that these information does not need to be repeated.


Type Members
class WithFilter extends FilterMonadic[A, Repr]
A class supporting filtered operations.

Abstract Value Members
def productArity : Int
The size of this product.
def productElement (n: Int): Any
The nth element of this product, 0-based.

Concrete Value Members
def ++ [B] (that: GenTraversableOnce[B]): List[B]
[use case] Concatenates this list with the elements of a traversable collection.
def ++ [B >: A, That] (that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
Concatenates this list with the elements of a traversable collection.
def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
def ++: [B >: A, That] (that: Traversable[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
This overload exists because: for the implementation of ++: we should reuse that of ++ because many collections override it with more efficient versions.
def ++: [B] (that: TraversableOnce[B]): List[B]
[use case] Concatenates this list with the elements of a traversable collection.
def ++: [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
Concatenates this list with the elements of a traversable collection.
def +: (elem: A): List[A]
[use case] Prepends an element to this list
def +: [B >: A, That] (elem: B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Prepends an element to this list
def /: [B] (z: B)(op: (B, A) ⇒ B): B
Applies a binary operator to a start value and all elements of this list, going left to right.
def /:\ [A1 >: A] (z: A1)(op: (A1, A1) ⇒ A1): A1
A syntactic sugar for out of order folding.
def :+ (elem: A): List[A]
[use case] Appends an element to this list
def :+ [B >: A, That] (elem: B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Appends an element to this list
def :: (x: A): List[A]
[use case] Adds an element at the beginning of this list.
def :: [B >: A] (x: B): List[B]
Adds an element at the beginning of this list.
def ::: (prefix: List[A]): List[A]
[use case] Adds the elements of a given list in front of this list.
def ::: [B >: A] (prefix: List[B]): List[B]
Adds the elements of a given list in front of this list.
def :\ [B] (z: B)(op: (A, B) ⇒ B): B
Applies a binary operator to all elements of this list and a start value, going right to left.

A
def addString (b: StringBuilder): StringBuilder
Appends all elements of this list to a string builder.
def addString (b: StringBuilder, sep: String): StringBuilder
Appends all elements of this list to a string builder using a separator string.
def addString (b: StringBuilder, start: String, sep: String, end: String): StringBuilder
Appends all elements of this list to a string builder using start, end, and separator strings.
def aggregate [B] (z: B)(seqop: (B, A) ⇒ B, combop: (B, B) ⇒ B): B
Aggregates the results of applying an operator to subsequent elements.
def andThen [C] (k: (A) ⇒ C): PartialFunction[Int, C]
Composes this partial function with a transformation function that gets applied to results of this partial function.
def apply (n: Int): A
Selects an element by its index in the list.

B

C
def canEqual (that: Any): Boolean
Method called from equality methods, so that user-defined subclasses can refuse to be equal to other collections of the same kind.
def collect [B] (pf: PartialFunction[A, B]): List[B]
[use case] Builds a new collection by applying a partial function to all elements of this list on which the function is defined.
def collect [B, That] (pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[List[A], B, That]): That
Builds a new collection by applying a partial function to all elements of this list on which the function is defined.
def collectFirst [B] (pf: PartialFunction[A, B]): Option[B]
Finds the first element of the list for which the given partial function is defined, and applies the partial function to it.
def combinations (n: Int): Iterator[List[A]]
Iterates over combinations.
def companion : GenericCompanion[List]
The factory companion object that builds instances of class List.
def compose [A] (g: (A) ⇒ Int): (A) ⇒ A
Composes two instances of Function1 in a new Function1, with this function applied last.
def contains (elem: Any): Boolean
Tests whether this list contains a given value as an element.
def containsSlice [B] (that: Seq[B]): Boolean
def containsSlice [B] (that: GenSeq[B]): Boolean
Tests whether this list contains a given sequence as a slice.
def copyToArray (xs: Array[A], start: Int, len: Int): Unit
[use case] Copies elements of this list to an array.
def copyToArray [B >: A] (xs: Array[B], start: Int, len: Int): Unit
Copies elements of this list to an array.
def copyToArray (xs: Array[A]): Unit
[use case] Copies values of this list to an array.
def copyToArray [B >: A] (xs: Array[B]): Unit
Copies values of this list to an array.
def copyToArray (xs: Array[A], start: Int): Unit
[use case] Copies values of this list to an array.
def copyToArray [B >: A] (xs: Array[B], start: Int): Unit
Copies values of this list to an array.
def copyToBuffer [B >: A] (dest: Buffer[B]): Unit
Copies all elements of this list to a buffer.
def corresponds [B] (that: Seq[B])(p: (A, B) ⇒ Boolean): Boolean
def corresponds [B] (that: GenSeq[B])(p: (A, B) ⇒ Boolean): Boolean
Tests whether every element of this list relates to the corresponding element of another sequence by satisfying a test predicate.
def count (p: (A) ⇒ Boolean): Int
Counts the number of elements in the list which satisfy a predicate.

D
def diff [B >: A] (that: Seq[B]): List[A]
def diff (that: Seq[A]): List[A]
[use case] Computes the multiset difference between this list and another sequence.
def diff [B >: A] (that: GenSeq[B]): List[A]
Computes the multiset difference between this list and another sequence.
def distinct : List[A]
Builds a new list from this list without any duplicate elements.
def drop (n: Int): List[A]
Selects all elements except first n ones.
def dropRight (n: Int): List[A]
Selects all elements except last n ones.
def dropWhile (p: (A) ⇒ Boolean): List[A]
Drops longest prefix of elements that satisfy a predicate.

E
def endsWith [B] (that: Seq[B]): Boolean
def endsWith [B] (that: GenSeq[B]): Boolean
Tests whether this list ends with the given sequence.
def equals (that: Any): Boolean
The equals method for arbitrary sequences.
def exists (p: (A) ⇒ Boolean): Boolean
Tests whether a predicate holds for some of the elements of this list.

F
def filter (p: (A) ⇒ Boolean): List[A]
Selects all elements of this list which satisfy a predicate.
def filterNot (p: (A) ⇒ Boolean): List[A]
Selects all elements of this list which do not satisfy a predicate.
def find (p: (A) ⇒ Boolean): Option[A]
Finds the first element of the list satisfying a predicate, if any.
def flatMap [B] (f: (A) ⇒ GenTraversableOnce[B]): List[B]
[use case] Builds a new collection by applying a function to all elements of this list and concatenating the results.
def flatMap [B, That] (f: (A) ⇒ GenTraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
Builds a new collection by applying a function to all elements of this list and concatenating the results.
def flatten [B] : List[B]
[use case] Converts this list of traversable collections into a list in which all element collections are concatenated.
def flatten [B] (implicit asTraversable: (A) ⇒ TraversableOnce[B]): Traversable[B]
Converts this list of traversable collections into a list in which all element collections are concatenated.
def fold [A1 >: A] (z: A1)(op: (A1, A1) ⇒ A1): A1
Folds the elements of this sequence using the specified associative binary operator.
def foldLeft [B] (z: B)(f: (B, A) ⇒ B): B
Applies a binary operator to a start value and all elements of this list, going left to right.
def foldRight [B] (z: B)(f: (A, B) ⇒ B): B
Applies a binary operator to all elements of this list and a start value, going right to left.
def forall (p: (A) ⇒ Boolean): Boolean
Tests whether a predicate holds for all elements of this list.
def foreach (f: (A) ⇒ Unit): Unit
[use case] Applies a function f to all elements of this list.
def foreach [B] (f: (A) ⇒ B): Unit
Applies a function f to all elements of this list.

G
def genericBuilder [B] : Builder[B, List[B]]
The generic builder that builds instances of List at arbitrary element types.
def groupBy [K] (f: (A) ⇒ K): Map[K, List[A]]
Partitions this list into a map of lists according to some discriminator function.
def grouped (size: Int): Iterator[List[A]]
Partitions elements in fixed size lists.

H
def hasDefiniteSize : Boolean
Tests whether this list is known to have a finite size.
def hashCode (): Int
Hashcodes for List produce a value from the hashcodes of all the elements of the list.
def head : A
Selects the first element of this list.
def headOption : Option[A]
Optionally selects the first element.

I
def indexOf (elem: A, from: Int): Int
[use case] Finds index of first occurrence of some value in this list after or at some start index.
def indexOf [B >: A] (elem: B, from: Int): Int
Finds index of first occurrence of some value in this list after or at some start index.
def indexOf (elem: A): Int
[use case] Finds index of first occurrence of some value in this list.
def indexOf [B >: A] (elem: B): Int
Finds index of first occurrence of some value in this list.
def indexOfSlice [B >: A] (that: Seq[B], from: Int): Int
def indexOfSlice [B >: A] (that: GenSeq[B], from: Int): Int
Finds first index after or at a start index where this list contains a given sequence as a slice.
def indexOfSlice [B >: A] (that: Seq[B]): Int
def indexOfSlice [B >: A] (that: GenSeq[B]): Int
Finds first index where this list contains a given sequence as a slice.
def indexWhere (p: (A) ⇒ Boolean, from: Int): Int
Finds index of the first element satisfying some predicate after or at some start index.
def indexWhere (p: (A) ⇒ Boolean): Int
Finds index of first element satisfying some predicate.
def indices : Range
Produces the range of all indices of this sequence.
def init : List[A]
Selects all elements except the last.
def inits : Iterator[List[A]]
Iterates over the inits of this list.
def intersect [B >: A] (that: Seq[B]): List[A]
def intersect (that: Seq[A]): List[A]
[use case] Computes the multiset intersection between this list and another sequence.
def intersect [B >: A] (that: GenSeq[B]): List[A]
Computes the multiset intersection between this list and another sequence.
def isDefinedAt (x: Int): Boolean
Tests whether this list contains given index.
def isEmpty : Boolean
Tests whether the list is empty.
def isTraversableAgain : Boolean
Tests whether this list can be repeatedly traversed.
def iterator : Iterator[A]
Creates a new iterator over all elements contained in this iterable object.

J

K

L
def last : A
Selects the last element.
def lastIndexOf (elem: A, end: Int): Int
[use case] Finds index of last occurrence of some value in this list before or at a given end index.
def lastIndexOf [B >: A] (elem: B, end: Int): Int
Finds index of last occurrence of some value in this list before or at a given end index.
def lastIndexOf (elem: A): Int
[use case] Finds index of last occurrence of some value in this list.
def lastIndexOf [B >: A] (elem: B): Int
Finds index of last occurrence of some value in this list.
def lastIndexOfSlice [B >: A] (that: Seq[B], end: Int): Int
def lastIndexOfSlice [B >: A] (that: GenSeq[B], end: Int): Int
Finds last index before or at a given end index where this list contains a given sequence as a slice.
def lastIndexOfSlice [B >: A] (that: Seq[B]): Int
def lastIndexOfSlice [B >: A] (that: GenSeq[B]): Int
Finds last index where this list contains a given sequence as a slice.
def lastIndexWhere (p: (A) ⇒ Boolean, end: Int): Int
Finds index of last element satisfying some predicate before or at given end index.
def lastIndexWhere (p: (A) ⇒ Boolean): Int
Finds index of last element satisfying some predicate.
def lastOption : Option[A]
Optionally selects the last element.
def length : Int
The length of the list.
def lengthCompare (len: Int): Int
Compares the length of this list to a test value.
def lift : (Int) ⇒ Option[A]
Turns this partial function into an plain function returning an Option result.

M
def map [B] (f: (A) ⇒ B): List[B]
[use case] Builds a new collection by applying a function to all elements of this list.
def map [B, That] (f: (A) ⇒ B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Builds a new collection by applying a function to all elements of this list.
def mapConserve (f: (A) ⇒ A): List[A]
[use case] Builds a new list by applying a function to all elements of this list.
def mapConserve [B >: A <: AnyRef] (f: (A) ⇒ B): List[B]
Builds a new list by applying a function to all elements of this list.
def max : A
[use case] Finds the largest element.
def max [B >: A] (implicit cmp: Ordering[B]): A
Finds the largest element.
def maxBy [B] (f: (A) ⇒ B)(implicit cmp: Ordering[B]): A
def min : A
[use case] Finds the smallest element.
def min [B >: A] (implicit cmp: Ordering[B]): A
Finds the smallest element.
def minBy [B] (f: (A) ⇒ B)(implicit cmp: Ordering[B]): A
def mkString : String
Displays all elements of this list in a string.
def mkString (sep: String): String
Displays all elements of this list in a string using a separator string.
def mkString (start: String, sep: String, end: String): String
Displays all elements of this list in a string using start, end, and separator strings.

N
def nonEmpty : Boolean
Tests whether the list is not empty.

O
def orElse [A1 <: Int, B1 >: A] (that: PartialFunction[A1, B1]): PartialFunction[A1, B1]
Composes this partial function with a fallback partial function which gets applied where this partial function is not defined.

P
def padTo (len: Int, elem: A): List[A]
[use case] Appends an element value to this list until a given target length is reached.
def padTo [B >: A, That] (len: Int, elem: B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Appends an element value to this list until a given target length is reached.
def par : ParSeq[A]
Returns a parallel implementation of this collection.
def partition (p: (A) ⇒ Boolean): (List[A], List[A])
Partitions this list in two lists according to a predicate.
def patch [B >: A, That] (from: Int, patch: Seq[B], replaced: Int)(implicit bf: CanBuildFrom[List[A], B, That]): That
def patch (from: Int, that: GenSeq[A], replaced: Int): List[A]
[use case] Produces a new list where a slice of elements in this list is replaced by another sequence.
def patch [B >: A, That] (from: Int, patch: GenSeq[B], replaced: Int)(implicit bf: CanBuildFrom[List[A], B, That]): That
Produces a new list where a slice of elements in this list is replaced by another sequence.
def permutations : Iterator[List[A]]
Iterates over distinct permutations.
def prefixLength (p: (A) ⇒ Boolean): Int
Returns the length of the longest prefix whose elements all satisfy some predicate.
def product : A
[use case] Multiplies up the elements of this collection.
def product [B >: A] (implicit num: Numeric[B]): B
Multiplies up the elements of this collection.
def productIterator : Iterator[Any]
An iterator over all the elements of this product.
def productPrefix : String
A string used in the toString methods of derived classes.

Q

R
def reduce [A1 >: A] (op: (A1, A1) ⇒ A1): A1
Reduces the elements of this sequence using the specified associative binary operator.
def reduceLeft [B >: A] (f: (B, A) ⇒ B): B
def reduceLeftOption [B >: A] (op: (B, A) ⇒ B): Option[B]
Optionally applies a binary operator to all elements of this list, going left to right.
def reduceOption [A1 >: A] (op: (A1, A1) ⇒ A1): Option[A1]
Optionally reduces the elements of this sequence using the specified associative binary operator.
def reduceRight [B >: A] (op: (A, B) ⇒ B): B
Applies a binary operator to all elements of this list, going right to left.
def reduceRightOption [B >: A] (op: (A, B) ⇒ B): Option[B]
Optionally applies a binary operator to all elements of this list, going right to left.
def repr : List[A]
The collection of type list underlying this TraversableLike object.
def reverse : List[A]
Returns new list wih elements in reversed order.
def reverseIterator : Iterator[A]
An iterator yielding elements in reversed order.
def reverseMap [B] (f: (A) ⇒ B): List[B]
[use case] Builds a new collection by applying a function to all elements of this list and collecting the results in reversed order.
def reverseMap [B, That] (f: (A) ⇒ B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Builds a new collection by applying a function to all elements of this list and collecting the results in reversed order.
def reverse_::: (prefix: List[A]): List[A]
[use case] Adds the elements of a given list in reverse order in front of this list.
def reverse_::: [B >: A] (prefix: List[B]): List[B]
Adds the elements of a given list in reverse order in front of this list.

S
def sameElements (that: GenIterable[A]): Boolean
[use case] Checks if the other iterable collection contains the same elements in the same order as this list.
def sameElements [B >: A] (that: GenIterable[B]): Boolean
Checks if the other iterable collection contains the same elements in the same order as this list.
def sameElements [B >: A] (that: Iterable[B]): Boolean
def scan [B >: A, That] (z: B)(op: (B, B) ⇒ B)(implicit cbf: CanBuildFrom[List[A], B, That]): That
Computes a prefix scan of the elements of the collection.
def scanLeft [B, That] (z: B)(op: (B, A) ⇒ B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Produces a collection containing cummulative results of applying the operator going left to right.
def scanRight [B, That] (z: B)(op: (A, B) ⇒ B)(implicit bf: CanBuildFrom[List[A], B, That]): That
Produces a collection containing cummulative results of applying the operator going right to left.
def segmentLength (p: (A) ⇒ Boolean, from: Int): Int
Computes length of longest segment whose elements all satisfy some predicate.
def seq : Seq[A]
A version of this collection with all of the operations implemented sequentially (i.
def size : Int
The size of this list, equivalent to length.
def slice (from: Int, until: Int): List[A]
Selects an interval of elements.
def sliding [B >: A] (size: Int, step: Int): Iterator[List[A]]
def sliding [B >: A] (size: Int): Iterator[List[A]]
Groups elements in fixed size blocks by passing a "sliding window" over them (as opposed to partitioning them, as is done in grouped.
def sortBy [B] (f: (A) ⇒ B)(implicit ord: Ordering[B]): List[A]
Sorts this List according to the Ordering which results from transforming an implicitly given Ordering with a transformation function.
def sortWith (lt: (A, A) ⇒ Boolean): List[A]
Sorts this list according to a comparison function.
def sorted [B >: A] (implicit ord: Ordering[B]): List[A]
Sorts this list according to an Ordering.
def span (p: (A) ⇒ Boolean): (List[A], List[A])
Splits this list into a prefix/suffix pair according to a predicate.
def splitAt (n: Int): (List[A], List[A])
Splits this list into two at a given position.
def startsWith [B] (that: Seq[B], offset: Int): Boolean
def startsWith [B] (that: GenSeq[B], offset: Int): Boolean
Tests whether this list contains the given sequence at a given index.
def startsWith [B] (that: Seq[B]): Boolean
def startsWith [B] (that: GenSeq[B]): Boolean
Tests whether this list starts with the given sequence.
def stringPrefix : String
Defines the prefix of this object's toString representation.
def sum : A
[use case] Sums up the elements of this collection.
def sum [B >: A] (implicit num: Numeric[B]): B
Sums up the elements of this collection.

T
def tail : List[A]
Selects all elements except the first.
def tails : Iterator[List[A]]
Iterates over the tails of this list.
def take (n: Int): List[A]
Selects first n elements.
def takeRight (n: Int): List[A]
Selects last n elements.
def takeWhile (p: (A) ⇒ Boolean): List[A]
Takes longest prefix of elements that satisfy a predicate.
def toArray : Array[A]
[use case] Converts this list to an array.
def toArray [B >: A] (implicit arg0: ClassManifest[B]): Array[B]
Converts this list to an array.
def toBuffer [B >: A] : Buffer[B]
Converts this list to a mutable buffer.
def toIndexedSeq [B >: A] : IndexedSeq[B]
Converts this list to an indexed sequence.
def toIterable : Iterable[A]
Converts this list to an iterable collection.
def toIterator : Iterator[A]
Returns an Iterator over the elements in this list.
def toList : List[A]
Converts this list to a list.
def toMap [T, U] : Map[T, U]
[use case] Converts this list to a map.
def toMap [T, U] (implicit ev: <:<[A, (T, U)]): Map[T, U]
Converts this list to a map.
def toSeq : Seq[A]
Converts this list to a sequence.
def toSet [B >: A] : Set[B]
Converts this list to a set.
def toStream : Stream[A]
Converts this list to a stream.
def toString (): String
Converts this list to a string.
def toTraversable : Traversable[A]
Converts this list to an unspecified Traversable.
def transpose [B] (implicit asTraversable: (A) ⇒ TraversableOnce[B]): Traversable[Traversable[B]]
Transposes this list of traversable collections into a list of lists.

U
def union (that: Seq[A]): List[A]
[use case] Produces a new sequence which contains all elements of this list and also all elements of a given sequence.
def union [B >: A, That] (that: GenSeq[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
Produces a new sequence which contains all elements of this list and also all elements of a given sequence.
def union [B >: A, That] (that: Seq[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
def unzip [A1, A2] (implicit asPair: (A) ⇒ (A1, A2)): (List[A1], List[A2])
Converts this list of pairs into two collections of the first and second half of each pair.
def unzip3 [A1, A2, A3] (implicit asTriple: (A) ⇒ (A1, A2, A3)): (List[A1], List[A2], List[A3])
Converts this list of triples into three collections of the first, second, and third element of each triple.
def updated (index: Int, elem: A): List[A]
[use case] A copy of this list with one single replaced element.
def updated [B >: A, That] (index: Int, elem: B)(implicit bf: CanBuildFrom[List[A], B, That]): That
A copy of this list with one single replaced element.

V
def view (from: Int, until: Int): SeqView[A, List[A]]
Creates a non-strict view of a slice of this list.
def view : SeqView[A, List[A]]
Creates a non-strict view of this list.

W
def withFilter (p: (A) ⇒ Boolean): FilterMonadic[A, List[A]]
Creates a non-strict filter of this list.

X

Y

Z
def zip [A1 >: A, B, That] (that: Iterable[B])(implicit bf: CanBuildFrom[List[A], (A1, B), That]): That
def zip [B] (that: GenIterable[B]): List[(A, B)]
[use case] Returns a list formed from this list and another iterable collection by combining corresponding elements in pairs.
def zip [A1 >: A, B, That] (that: GenIterable[B])(implicit bf: CanBuildFrom[List[A], (A1, B), That]): That
Returns a list formed from this list and another iterable collection by combining corresponding elements in pairs.
def zipAll [B, A1 >: A, That] (that: Iterable[B], thisElem: A1, thatElem: B)(implicit bf: CanBuildFrom[List[A], (A1, B), That]): That
def zipAll [B] (that: Iterable[B], thisElem: A, thatElem: B): List[(A, B)]
[use case] Returns a list formed from this list and another iterable collection by combining corresponding elements in pairs.
def zipAll [B, A1 >: A, That] (that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CanBuildFrom[List[A], (A1, B), That]): That
Returns a list formed from this list and another iterable collection by combining corresponding elements in pairs.
def zipWithIndex : List[(A, Int)]
[use case] Zips this list with its indices.
def zipWithIndex [A1 >: A, That] (implicit bf: CanBuildFrom[List[A], (A1, Int), That]): That
Zips this list with its indices.

Authored by Win Myo Htet