Scala provides a number of traits and classes for handling collections of objects.

This page is intended to give an overview of the general structure of the collections library, concentrating on the important traits and classes without attempting to exhaustively list the intermediate traits, mixins, etc.

The main traits are part of the scala package, and thus are automatically imported into all programs.

The implementation classes are separated into three separate packages:

• scala.collection.immutable contains immutable implementations
• scala.collection.mutable contains mutable implementations
• scala.collection.jcl contains wrappers for Java’s collection library

Some implementation classes are available in all three packages, some in just two packages, and some in just one of the packages. A few implementation classes – notably List, Array, and Range – are located in the base scala package.

The Iterable trait is the base trait for all of Scala’s collections. It includes all of the methods necessary to be used in for comprehensions.

Notably absent from the Iterable trait is any way of determining how many items are present. An object that conforms to Iterable might be generating results on the fly, or might not know a priori how many items are going to be provided. Since the number of items might be infinite, no toString() method is provided, either.

Scala does not provide any collection classes that directly implement Iterable.

The Collection trait adds the size() and toString() methods to Iterable. This is the base trait for all of Scala’s provided collection classes.

There are three major types of collection: Set, Map, and Seq.

The Set trait encompasses collections of unduplicated objects.

Scala set classes include:

• Set1 through Set4 – immutable only
• HashSet – immutable, mutable, Java
• ListSet – immutable only
• LinkedHashSet – mutable and Java only
• BitSet – immutable and mutable only
• TreeSet – immutable and Java only

All Set classes define the apply() method to allow shorthand access:

val isPresent = aSet(aValue)

Mutable and Java Set classes also define the update() method to allow shorthand additions and deletions:

aHashSet(aValue) = true    // or false to remove

The immutable and mutable Set classes, the immutable and mutable HashSet classes, and the immutable TreeSet class have companion objects with an apply() method to allow shorthand creation:

val aSet = Set(1,2,3,4)
val aHashSet = HashSet(1,2,3,4)
val aTreeSet = TreeSet(1,2,3,4)

The immutable Set companion object will create objects of type Set1 through Set4 when appropriate.

If not specified, the immutable version of Set is assumed due to a type definition in Predef. While convenient for creating set objects without needing to use an import, this can cause unanticipated type errors:

import scala.collection.mutable.HashSet
val aSet: Set[int] = new HashSet[int]                    // wrong
val aSet: scala.collection.Set[int] = new HashSet[int]   // right

The Map trait encompasses indexed collections.

Scala map classes include:

• Map1 through Map4 – immutable only
• HashMap – immutable, mutable, Java
• ListMap – immutable only
• TreeMap – immutable and Java only
• UnbalancedTreeMap – immutable only
• LinkedHashMap – Java only
• IdentityHashMap – Java only
• WeakHashMap – Java only

The Java class Hashtable is not wrapped by Scala. Scala has a trait called HashTable but it is something different.

Scala maps are partial functions. The get() method returns an Option object rather than the bare result value. To get the same effect as a Java Map which returns bare values – or null when the key is missing – use:

val aValue = aMap.getOrElse(aKey,null)

Using the Option return value is arguably a better approach, though.

All Map classes define the apply() method to allow shorthand access:

val aValue = aMap(aKey)

However, this technique assumes that the key is present in the map. If the key is not present, an exception will be thrown. If the key might be absent, it is the programmer’s duty to test for this by calling isDefinedAt() or contains().

Mutable and Java Map classes also define the update() method to allow shorthand additions and updates (but not deletions):

aMap(aKey) = aValue

The immutable and mutable Map classes, the immutable and mutable HashMap classes, and the immutable TreeMap and UnbalancedTreeMap classes have companion objects with an apply() method to allow shorthand creation:

val aMap = Map(("key1","val1"),("key2","val2"))
val aHashMap = HashMap(("key1","val1"),("key2","val2"))
val aTreeMap = TreeMap(("key1","val1"),("key2","val2"))
val anUnbalancedTreeMap = UnbalancedTreeMap(("key1","val1"),("key2","val2"))

If not specified, the immutable version of Map is assumed due to a type definition in Predef. While convenient for creating map objects without needing to use an import, this can cause unanticipated type errors:

import scala.collection.mutable.HashMap
val aMap: Map[int,int] = new HashMap[int,int]                   // wrong
val aMap: scala.collection.Map[int,int] = new HashMap[int,int]  // right

The Seq trait encompasses sequence collections.

All sequence classes provide the apply() method to allow shorthand access. For example:

val aValue = aList(anIndex)
val aValue = anArray(anIndex)

In addition to ordinary sequence classes, there are two subgroups: RandomAccessSeq and Buffer. There also is a derived trait Stream which is not covered here.

Scala sequence classes include:

• Queue – immutable and mutable only
• Stack – immutable and mutable only
• List – immutable only (located in the base scala package)
• LinkedList – mutable only (there is a separate Java implementation)

The mutable version of LinkedList is an implementation of SingleLinkedList, in contrast to the Java version which is a double-linked list. Scala provides an abstract class for DoubleLinkedList but does not provide a standard implementation.

The List class has a companion object with apply() methods to allow shorthand creation:

val aList = List(1,2,3,4)

The RandomAccessSeq trait encompasses sequences where individual elements can be accessed in O(1) time.

Scala random access sequence classes include:

• Range – immutable only (located in the base scala package)
• Array – mutable only (located in the base scala package)
• PriorityQueue – mutable only
• ArrayBuffer – mutable only
• ArrayList – Java only

The Java class Vector is not wrapped by Scala.

The Range class is a virtual collection rather than a true collection of actual objects. The Range class is (currently) the only Scala-provided collection class that is implemented as a projection.

The Array and ArrayBuffer classes define the update() method (in addition to apply()) to allow shorthand replacement:

anArray(anIndex) = aValue
anBufferArray(anIndex) = aValue

The Array class has a companion object with apply() methods to allow shorthand creation:

val anArray = Array(1,2,3,4)

The Buffer trait encompasses mutable sequences that can be modified by appending, inserting, deleting, and replacing elements.

Scala buffer classes include:

• ListBuffer – mutable only
• ArrayBuffer – mutable only
• LinkedList – Java only (there is a separate mutable implementation)

All Buffer classes define the update() method (in addition to apply()) to allow shorthand replacement:

aBuffer(anIndex) = aValue