diff options
author | Heather Miller <heather.miller@epfl.ch> | 2011-08-21 00:29:10 +0000 |
---|---|---|
committer | Heather Miller <heather.miller@epfl.ch> | 2011-08-21 00:29:10 +0000 |
commit | cecee085f345097055737f318e0ef30a02b7ac96 (patch) | |
tree | 39982ef201b646dee617a5b254f73aaf9d5d0c6d /src/library/scala/collection/immutable/List.scala | |
parent | 7e99a7d380d7a6331e456ab032a5994d268d37fc (diff) | |
download | scala-cecee085f345097055737f318e0ef30a02b7ac96.tar.gz scala-cecee085f345097055737f318e0ef30a02b7ac96.tar.bz2 scala-cecee085f345097055737f318e0ef30a02b7ac96.zip |
Improved documentation for scala.collection.imm...
Improved documentation for scala.collection.immutable.List and
scala.collection.immutable.Queue. Contributed by Matthew Pocock during
the Monthly Docspree. Review by phaller.
Diffstat (limited to 'src/library/scala/collection/immutable/List.scala')
-rw-r--r-- | src/library/scala/collection/immutable/List.scala | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala index 5791e9788d..fb7808bc41 100644 --- a/src/library/scala/collection/immutable/List.scala +++ b/src/library/scala/collection/immutable/List.scala @@ -22,6 +22,38 @@ import annotation.tailrec * and `scala.::` that implement the abstract members `isEmpty`, * `head` and `tail`. * + * This class is optimal for last-in-first-out (LIFO), stack-like access patterns. If you need another access + * pattern, for example, random access or FIFO, consider using a collection more suited to this than `List`. + * + * @example {{{ + * // Make a list via the companion object factory + * val days = List("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday") + * + * // Make a list element-by-element + * val when = "AM" :: "PM" :: List() + * + * // Pattern match + * days match { + * case firstDay :: otherDays => + * println("The first day of the week is: " + firstDay) + * case List() => + * println("There don't seem to be any week days.") + * } + * }}} + * + * ==Performance== + * '''Time:''' `List` has `O(1)` prepend and head/tail access. Most other operations are `O(n)` on the number of elements in the list. + * This includes the index-based lookup of elements, `length`, `append` and `reverse`. + * + * '''Space:''' `List` implements '''structural sharing''' of the tail list. This means that many operations are either + * zero- or constant-memory cost. + * {{{ + * val mainList = List(3, 2, 1) + * val with4 = 4 :: mainList // re-uses mainList, costs one :: instance + * val with42 = 42 :: mainList // also re-uses mainList, cost one :: instance + * val shorter = mainList.tail // costs nothing as it uses the same 2::1::Nil instances as mainList + * }}} + * * @author Martin Odersky and others * @version 2.8 * @since 1.0 |