Learning Scala : Reading the exotic and essential List API scaladoc 12

Authored by Win Myo Htet

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 partition (p: (A) ⇒ Boolean): (List[A], List[A])
Partitions this list in two lists according to a predicate.

def grouped (size: Int): Iterator[List[A]]
Partitions elements in fixed size lists.
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 sliding [B >: A] (size: Int, step: Int): Iterator[List[A]]
Sorts this List according to the Ordering which results from transforming an implicitly given Ordering with a transformation function.

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.

genericBuilder return a Builder, through which we can create the same collection type, in our case List(you might want to look up a similar function, companion, covered here.) In contrast with companion function is that you have to call function result to get the desired collection(List) type from the (List)buffer.
groupBy return the-function-defined-partition of the List as a value and it is mapped to the key. We demonstrate this by partitioning the List in terms of the modulo of 3. Lists of Odd and Even partitioning is considered for the demonstration but groupBy is capable of partitioning more than two Lists unlike the following function, thus the modulo of 3 example is used.
The function partition returns two partitions, which either satisfies the predicate or not. We have a tuple of two resulting Lists: Odd List and Even List.
grouped return iterator to get a List of n elements.
sliding is better described in the code snippet.
hasDefiniteSize is to differentiate collection, like Stream, which has infinite size, and other collection, which does not have infinite size. List does not have infinite size. hashCode return hashCode.

scala> val list = (for (i <- 1 to 11) yield i) toList
list: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)

scala> val bldr = list.genericBuilder[Int] += (5,6,7)
bldr: scala.collection.mutable.Builder[Int,List[Int]] = ListBuffer(5, 6, 7)

scala> bldr.result
res0: List[Int] = List(5, 6, 7)

scala> list.genericBuilder[String] += ("a","b","c")
res1: scala.collection.mutable.Builder[String,List[String]] = ListBuffer(a, b, c)

scala> list groupBy { case x:Int if x % 3 == 0 => "0"; case x:Int if x % 3 == 1 => "1" ; case x:Int if x % 3 == 2 => "2"}
res2: scala.collection.immutable.Map[java.lang.String,List[Int]] = Map(0 -> List(3, 6, 9), 1 -> List(1, 4, 7, 10), 2 -> List(2, 5, 8, 11))

scala> list partition ( x => x % 2 == 0)
res3: (List[Int], List[Int]) = (List(2, 4, 6, 8, 10),List(1, 3, 5, 7, 9, 11))

scala> for ( x <- list grouped 3) println(x)
List(1, 2, 3)
List(4, 5, 6)
List(7, 8, 9)
List(10, 11)

scala> for ( x <- list sliding 3) println(x)
List(1, 2, 3)
List(2, 3, 4)
List(3, 4, 5)
List(4, 5, 6)
List(5, 6, 7)
List(6, 7, 8)
List(7, 8, 9)
List(8, 9, 10)
List(9, 10, 11)

for (x <- list.sliding(4,2)) println(x)
List(1, 2, 3, 4)
List(3, 4, 5, 6)
List(5, 6, 7, 8)
List(7, 8, 9, 10)
List(9, 10, 11)

scala> list hasDefiniteSize
res6: Boolean = true

scala> list hashCode
res7: Int = -1287208638

def head : A
Selects the first element of this list.
def headOption : Option[A]
Optionally selects the first element.
def last : A
Selects the last element.
def lastOption : Option[A]
Optionally selects the last element.

def tail : List[A]
Selects all elements except the first.
def tails : Iterator[List[A]]
Iterates over the tails of this list.
def init : List[A]
Selects all elements except the last.
def inits : Iterator[List[A]]
Iterates over the inits of this list.

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

We know head and tail early when we start reading about Scala. Here we have brought their relatives together along with its counterpart family of last(head) and init(tail). isEmpty or noEmpty? These two methods serve the same purpose. The reason for two functions for a single purpose is for self-documenting. One can see that in comment of TraversableOnce source at line 62.

scala> list head
res8: Int = 1

scala> list headOption
res9: Option[Int] = Some(1)

scala> list last
res10: Int = 11

scala> list lastOption
res11: Option[Int] = Some(11)

scala>  list tail
res12: List[Int] = List(2, 3, 4, 5, 6, 7, 8, 9, 10, 11)

scala> for (x <- list tails) println(x)
List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)
List(2, 3, 4, 5, 6, 7, 8, 9, 10, 11)
List(3, 4, 5, 6, 7, 8, 9, 10, 11)
List(4, 5, 6, 7, 8, 9, 10, 11)
List(5, 6, 7, 8, 9, 10, 11)
List(6, 7, 8, 9, 10, 11)
List(7, 8, 9, 10, 11)
List(8, 9, 10, 11)
List(9, 10, 11)
List(10, 11)
List(11)
List()

scala> list init
res14: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)

scala> for (x <- list inits) println(x)
List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)
List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
List(1, 2, 3, 4, 5, 6, 7, 8, 9)
List(1, 2, 3, 4, 5, 6, 7, 8)
List(1, 2, 3, 4, 5, 6, 7)
List(1, 2, 3, 4, 5, 6)
List(1, 2, 3, 4, 5)
List(1, 2, 3, 4)
List(1, 2, 3)
List(1, 2)
List(1)
List()

scala> list isEmpty
res16: Boolean = false

scala> list nonEmpty
res17: Boolean = true

Authored by Win Myo Htet