1
 
2
  /*                     __                                               *\
3
  **     ________ ___   / /  ___     Scala API                            **
4
  **    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
5
  **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
6
  ** /____/\___/_/ |_/____/_/ | |                                         **
7
  **                          |/                                          **
8
  \*                                                                      */
9
 
10
  package scala.collection
11
 
12
  import generic._
13
  import mutable.{ Builder, ListBuffer }
14
  import annotation.{tailrec, migration, bridge}
15
  import annotation.unchecked.{ uncheckedVariance => uV }
16
  import parallel.ParIterable
17
 
18
  /** A template trait for traversable collections of type `Traversable[A]`.
19
   *  
20
   *  $traversableInfo
21
   *  @define mutability
22
   *  @define traversableInfo
23
   *  This is a base trait of all kinds of $mutability Scala collections. It
24
   *  implements the behavior common to all collections, in terms of a method
25
   *  `foreach` with signature:
26
   * {{{
27
   *     def foreach[U](f: Elem => U): Unit
28
   * }}}
29
   *  Collection classes mixing in this trait provide a concrete 
30
   *  `foreach` method which traverses all the
31
   *  elements contained in the collection, applying a given function to each.
32
   *  They also need to provide a method `newBuilder`
33
   *  which creates a builder for collections of the same kind.
34
   *  
35
   *  A traversable class might or might not have two properties: strictness
36
   *  and orderedness. Neither is represented as a type.
37
   *  
38
   *  The instances of a strict collection class have all their elements
39
   *  computed before they can be used as values. By contrast, instances of
40
   *  a non-strict collection class may defer computation of some of their
41
   *  elements until after the instance is available as a value.
42
   *  A typical example of a non-strict collection class is a
43
   *  <a href="../immutable/Stream.html" target="ContentFrame">
44
   *  `scala.collection.immutable.Stream`</a>.
45
   *  A more general class of examples are `TraversableViews`.
46
   *  
47
   *  If a collection is an instance of an ordered collection class, traversing
48
   *  its elements with `foreach` will always visit elements in the
49
   *  same order, even for different runs of the program. If the class is not
50
   *  ordered, `foreach` can visit elements in different orders for
51
   *  different runs (but it will keep the same order in the same run).'
52
   * 
53
   *  A typical example of a collection class which is not ordered is a
54
   *  `HashMap` of objects. The traversal order for hash maps will
55
   *  depend on the hash codes of its elements, and these hash codes might
56
   *  differ from one run to the next. By contrast, a `LinkedHashMap`
57
   *  is ordered because it's `foreach` method visits elements in the
58
   *  order they were inserted into the `HashMap`.