/*                     __                                               *\

  **     ________ ___   / /  ___     Scala API                            **

  **    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **

  **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **

  ** /____/\___/_/ |_/____/_/ | |                                         **

  **                          |/                                          **

  \*                                                                      */

  package scala.collection

  import generic._

  import mutable.{ Builder, ListBuffer }

  import annotation.{tailrec, migration, bridge}

  import annotation.unchecked.{ uncheckedVariance => uV }

  import parallel.ParIterable

  /** A template trait for traversable collections of type `Traversable[A]`.

   *  

   *  $traversableInfo

   *  @define mutability

   *  @define traversableInfo

   *  This is a base trait of all kinds of $mutability Scala collections. It

   *  implements the behavior common to all collections, in terms of a method

   *  `foreach` with signature:

   * {{{

   *     def foreach[U](f: Elem => U): Unit

   * }}}

   *  Collection classes mixing in this trait provide a concrete 

   *  `foreach` method which traverses all the

   *  elements contained in the collection, applying a given function to each.

   *  They also need to provide a method `newBuilder`

   *  which creates a builder for collections of the same kind.

   *  

   *  A traversable class might or might not have two properties: strictness

   *  and orderedness. Neither is represented as a type.

   *  

   *  The instances of a strict collection class have all their elements

   *  computed before they can be used as values. By contrast, instances of

   *  a non-strict collection class may defer computation of some of their

   *  elements until after the instance is available as a value.

   *  A typical example of a non-strict collection class is a

   *  <a href="../immutable/Stream.html" target="ContentFrame">

   *  `scala.collection.immutable.Stream`</a>.

   *  A more general class of examples are `TraversableViews`.

   *  

   *  If a collection is an instance of an ordered collection class, traversing

   *  its elements with `foreach` will always visit elements in the

   *  same order, even for different runs of the program. If the class is not

   *  ordered, `foreach` can visit elements in different orders for

   *  different runs (but it will keep the same order in the same run).'

   * 

   *  A typical example of a collection class which is not ordered is a

   *  `HashMap` of objects. The traversal order for hash maps will

   *  depend on the hash codes of its elements, and these hash codes might

   *  differ from one run to the next. By contrast, a `LinkedHashMap`

   *  is ordered because it's `foreach` method visits elements in the

   *  order they were inserted into the `HashMap`.