Added sizeHints to operations where it made sense.

1 files changed, 36 insertions, 0 deletions

diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index a930c29948..0c8bb79f83 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -52,6 +52,42 @@ trait Builder[-Elem, +To] extends Growable[Elem] {
    */
   def sizeHint(size: Int) {}
 
+  /** Gives a hint that one expects the `result` of this builder
+   *  to have the same size as the given collection, plus some delta. This will
+   *  provide a hint only if the collection is known to have a cheap
+   *  `size` method. Currently this is assumed ot be the case if and only if
+   *  the collection is of type `IndexedSeqLike`.
+   *  Some builder classes
+   *  will optimize their representation based on the hint. However,
+   *  builder implementations are still required to work correctly even if the hint is
+   *  wrong, i.e. a different number of elements is added.
+   *
+   *  @param coll  the collection which serves as a hint for the result's size.
+   *  @param delta a correction to add to the `coll.size` to produce the size hint.
+   */
+  def sizeHint(coll: TraversableLike[_, _], delta: Int = 0) {
+    if (coll.isInstanceOf[IndexedSeqLike[_,_]]) {
+      sizeHint(coll.size + delta)
+    }
+  }
+
+  /** Gives a hint how many elements are expected to be added
+   *  when the next `result` is called, together with an upper bound
+   *  given by the size of some other collection. Some builder classes
+   *  will optimize their representation based on the hint. However,
+   *  builder implementations are still required to work correctly even if the hint is
+   *  wrong, i.e. a different number of elements is added.
+   *
+   *  @param size  the hint how many elements will be added.
+   *  @param boundingColl  the bounding collection. If it is
+   *                       an IndexedSeqLike, then sizes larger
+   *                       than collection's size are reduced.
+   */
+  def sizeHintBounded(size: Int, boundingColl: TraversableLike[_, _]) {
+    if (boundingColl.isInstanceOf[IndexedSeqLike[_,_]])
+      sizeHint(size min boundingColl.size)
+  }
+
   /** Creates a new builder by applying a transformation function to
    *  the results of this builder.
    *  @param  f     the transformation function.