Scala mode /* __ *\ ** ________ ___ / / ___ 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 * * `scala.collection.immutable.Stream`. * 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`. * * @author Martin Odersky * @version 2.8 * @since 2.8 * @tparam A the element type of the collection * @tparam Repr the type of the actual collection containing the elements. * * @define Coll Traversable * @define coll traversable collection */ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] with FilterMonadic[A, Repr] with TraversableOnce[A] with GenTraversableLike[A, Repr] with Parallelizable[A, ParIterable[A]] { self => import Traversable.breaks._ /** The type implementing this traversable */ protected type Self = Repr /** The collection of type $coll underlying this `TraversableLike` object. * By default this is implemented as the `TraversableLike` object itself, * but this can be overridden. */ def repr: Repr = this.asInstanceOf[Repr] /** The underlying collection seen as an instance of `$Coll`. * By default this is implemented as the current collection object itself, * but this can be overridden. */ protected[this] def thisCollection: Traversable[A] = this.asInstanceOf[Traversable[A]] /** A conversion from collections of type `Repr` to `$Coll` objects. * By default this is implemented as just a cast, but this can be overridden. */ protected[this] def toCollection(repr: Repr): Traversable[A] = repr.asInstanceOf[Traversable[A]] /** Creates a new builder for this collection type. */ protected[this] def newBuilder: Builder[A, Repr] protected[this] def parCombiner = ParIterable.newCombiner[A] /** Applies a function `f` to all elements of this $coll. * * Note: this method underlies the implementation of most other bulk operations. * It's important to implement this method in an efficient way. * * * @param f the function that is applied for its side-effect to e