/collection-strawman

Experimenting with Scala Collections designs for Scala 2.13

Primary LanguageScala

Collection-Strawman

Join the chat at https://gitter.im/scala/collection-strawman Waffle.io board

Prototype improvements for Scala collections.

Current status

The strawman is available as a regular external library (see below usage instructions). The collections live in the strawman.collection namespace (instead of scala.collection).

Almost all operations and collection types of the current standard collections are available. If you see something missing, please create an issue.

Use it in your project

Build setup

Add the following dependency to your project:

libraryDependencies += "ch.epfl.scala" %% "collection-strawman" % "0.8.0"
libraryDependencies += "ch.epfl.scala" %% "collections-contrib" % "0.8.0" // optional

The 0.8.0 version is compatible with Scala 2.13 and Dotty 0.6. Scala 2.12 is also supported but you might encounter type inference issues with it.

We also automatically publish snapshots on Sonatype:

resolvers += Resolver.sonatypeRepo("snapshots")

libraryDependencies += "ch.epfl.scala" %% "collection-strawman" % "0.9.0-SNAPSHOT"

The collections-contrib artifact provides additional operations on the collections (see the Additional operations section).

API Documentation

Migrating from the standard collections to the strawman

A tool is being developed to automatically migrate code that uses the standard collection to use the strawman.

To use it, add the scalafix sbt plugin to your build, as explained in its documentation.

Two situations are supported: (1) migrating a 2.12 code base to a 2.12 code base that uses the collection strawman as a library (instead of the standard collections), and (2) migrating a 2.12 code base to 2.13 code base.

The migration tool is not exhaustive and we will continue to improve it over time. If you encounter a use case that’s not supported, please report it as described in the contributing documentation.

Migrating a 2.12 code base to a 2.12 code base that uses the collection strawman as a library

Run the following sbt task on your project:

> scalafix https://github.com/scala/collection-strawman/raw/master/scalafix/2.12/rules/src/main/scala/fix/Collectionstrawman_v0.scala

In essence, the migration tool changes the imports in your source code so that the strawman definitions are imported. It also rewrites expressions that use an API that is different in the strawman.

Migrating a 2.12 code base to 2.13 code base

Run the following sbt task on your project:

> scalafix https://github.com/scala/collection-strawman/raw/master/scalafix/2.13/rules/src/main/scala/fix/Collectionstrawman_v0.scala

Additional Operations

The collections-contrib artifact provides decorators enriching the collections with new operations. You can think of this artifact as an incubator: if we get evidence that these operations should be part of the core, we might eventually move them.

The new operations are provided via an implicit enrichment. You need to add the following import to make them available:

import strawman.collection.decorators._

The following operations are provided:

  • Seq
    • intersperse
  • Map
    • zipByKey / join / zipByKeyWith
    • mergeByKey / fullOuterJoin / mergeByKeyWith / leftOuterJoin / rightOuterJoin

The following collections are provided:

  • MultiSet (both mutable and immutable)
  • SortedMultiSet (both mutable and immutable)

Roadmap

  1. September 2017: release targeting Scala 2.13 and Dotty.
    • Implement most of the current collections types
    • Implement most of the current collections operations
    • Alternative to CanBuildFrom to get implicit builders
    • Include tests for correctness (taken from the current collections and from scala-collections-laws)
    • Provide a rewriting tool that migrates a code base from the current collections to the strawman
  2. November 2017: move to the scala namespace
    • Create a branch of Scala 2.13 with the strawman instead of the current collections
  3. January 2018: new features and performance improvements
    • Add Scala.js support
    • Consider the inclusion of new collection types (such as Spandex, Steque or ArrayDeque)
    • Consider the introduction of new operations (such as database-like joins, variants of groupBy, etc.)
    • Java interoperability
    • Separate project for parallel collections

Contributing

We welcome contributions!

For more information, see the CONTRIBUTING file.

Implemented collection types

  • List
  • LazyList (aka Stream in 2.12)
  • Queue
  • Stack
  • ArrayOps
  • StringOps
  • ArrayBuffer
  • ImmutableArray (new)
  • ListBuffer
  • UnrolledBuffer
  • LinkedList
  • DoubleLinkedList
  • Range / NumericRange
  • Vector
  • HashMap
  • mutable.LinkedHashMap
  • TreeMap
  • IntMap / LongMap (?)
  • ListMap
  • MultiMap
  • HashSet
  • mutable.LinkedHashSet
  • ListSet
  • TreeSet
  • EqSet
  • BitSet
  • View

Implemented operations (on the relevant collection types)

Operations not returning a collection

  • apply
  • contains
  • containsSlice
  • count
  • endsWith
  • find
  • firstKey
  • forall / exists
  • foreach
  • foldLeft
  • foldRight
  • get
  • getOrElse
  • getOrElseUpdate
  • head
  • indexOf / indexWhere / lastIndexOf / lastIndexWhere / indexOfSlice / lastIndexOfSlice
  • indices
  • isDefinedAt
  • isEmpty / nonEmpty
  • iteratorFrom / keysIteratorFrom / valuesIteratorFrom
  • last / lastOption
  • lastKey
  • max / maxBy
  • min / minBy
  • mkString
  • product
  • reduce / reduceOption / reduceLeft / reduceRight
  • size
  • span
  • startsWith
  • sum
  • to

Transformations to collections having the same element type

  • diff
  • distinct / distinctBy
  • drop / dropRight / dropWhile
  • empty
  • filter / filterNot / filterKeys
  • groupBy
  • init
  • intersect
  • partition
  • range / rangeTo
  • rangeImpl
  • sorted / sortBy / sortWith
  • slice
  • splitAt
  • substetOf
  • subsets
  • tail
  • take / takeRight / takeWhile
  • updated
  • withDefault / withDefaultValue

Transformations to collections that can have a different element type

  • combinations
  • updated
  • prepend
  • append
  • ++ / concat / union
  • ++: / prependAll
  • flatMap
  • grouped
  • keys / keySet / keysIterator
  • map / mapValues
  • merged
  • padTo
  • permutations
  • scan / scanLeft / scanRight
  • sliding
  • unzip
  • values / valuesIterator
  • zip / zipWithIndex / lazyZip

In-place mutating operations

TODO