Clarified and expanded which Builders were reusable

This additionally fixes both SI-8648 and SI-9564.

Added documentation to Builder to clarify that in general Builders are NOT reusable.

Altered implementation of GrowingBuilder to use Growable instance's clear (not valid for a reusable builder, but this one isn't reusable).

Added a new marker trait ReusableBuilder that specifies that these builders should be reusable.  This trait overrides the clear and result methods while leaving them abstract in order to supply appropriate scaladoc.

Made all Array builders Reusable in all cases (by setting capacity to 0 if the original array is returned).  (Fixed a poor implmentation of Array[Unit] builder along the way.)

Documented which other builders were already reusable (maps, sets, Vector, LazyBuilder, StringBuilder, ListBuffer, etc.).

1 files changed, 66 insertions, 87 deletions

diff --git a/src/library/scala/collection/mutable/ArrayBuilder.scala b/src/library/scala/collection/mutable/ArrayBuilder.scala
index ac78ab823b..549ffef565 100644
--- a/src/library/scala/collection/mutable/ArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/ArrayBuilder.scala
@@ -18,7 +18,7 @@ import scala.reflect.ClassTag
  *
  *  @tparam T    the type of the elements for the builder.
  */
-abstract class ArrayBuilder[T] extends Builder[T, Array[T]] with Serializable
+abstract class ArrayBuilder[T] extends ReusableBuilder[T, Array[T]] with Serializable
 
 /** A companion object for array builders.
  *
@@ -49,6 +49,8 @@ object ArrayBuilder {
 
   /** A class for array builders for arrays of reference types.
    *
+   *  This builder can be reused.
+   *
    *  @tparam T     type of elements for the array builder, subtype of `AnyRef` with a `ClassTag` context bound.
    */
   @deprecatedInheritance("ArrayBuilder.ofRef is an internal implementation not intended for subclassing.", "2.11.0")
@@ -98,12 +100,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -115,7 +118,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofRef"
   }
 
-  /** A class for array builders for arrays of `byte`s. */
+  /** A class for array builders for arrays of `byte`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofByte is an internal implementation not intended for subclassing.", "2.11.0")
   class ofByte extends ArrayBuilder[Byte] {
 
@@ -163,12 +166,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -180,7 +184,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofByte"
   }
 
-  /** A class for array builders for arrays of `short`s. */
+  /** A class for array builders for arrays of `short`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofShort is an internal implementation not intended for subclassing.", "2.11.0")
   class ofShort extends ArrayBuilder[Short] {
 
@@ -228,12 +232,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -245,7 +250,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofShort"
   }
 
-  /** A class for array builders for arrays of `char`s. */
+  /** A class for array builders for arrays of `char`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofChar is an internal implementation not intended for subclassing.", "2.11.0")
   class ofChar extends ArrayBuilder[Char] {
 
@@ -293,12 +298,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -310,7 +316,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofChar"
   }
 
-  /** A class for array builders for arrays of `int`s. */
+  /** A class for array builders for arrays of `int`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofInt is an internal implementation not intended for subclassing.", "2.11.0")
   class ofInt extends ArrayBuilder[Int] {
 
@@ -358,12 +364,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -375,7 +382,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofInt"
   }
 
-  /** A class for array builders for arrays of `long`s. */
+  /** A class for array builders for arrays of `long`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofLong is an internal implementation not intended for subclassing.", "2.11.0")
   class ofLong extends ArrayBuilder[Long] {
 
@@ -423,12 +430,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -440,7 +448,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofLong"
   }
 
-  /** A class for array builders for arrays of `float`s. */
+  /** A class for array builders for arrays of `float`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofFloat is an internal implementation not intended for subclassing.", "2.11.0")
   class ofFloat extends ArrayBuilder[Float] {
 
@@ -488,12 +496,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -505,7 +514,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofFloat"
   }
 
-  /** A class for array builders for arrays of `double`s. */
+  /** A class for array builders for arrays of `double`s. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofDouble is an internal implementation not intended for subclassing.", "2.11.0")
   class ofDouble extends ArrayBuilder[Double] {
 
@@ -553,12 +562,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -570,7 +580,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofDouble"
   }
 
-  /** A class for array builders for arrays of `boolean`s. */
+  /** A class for array builders for arrays of `boolean`s. It can be reused. */
   class ofBoolean extends ArrayBuilder[Boolean] {
 
     private var elems: Array[Boolean] = _
@@ -617,12 +627,13 @@ object ArrayBuilder {
         super.++=(xs)
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
+      if (capacity != 0 && capacity == size) {
+        capacity = 0
+        elems
+      }
       else mkArray(size)
     }
 
@@ -634,65 +645,33 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofBoolean"
   }
 
-  /** A class for array builders for arrays of `Unit` type. */
+  /** A class for array builders for arrays of `Unit` type. It can be reused. */
   @deprecatedInheritance("ArrayBuilder.ofUnit is an internal implementation not intended for subclassing.", "2.11.0")
   class ofUnit extends ArrayBuilder[Unit] {
 
-    private var elems: Array[Unit] = _
-    private var capacity: Int = 0
     private var size: Int = 0
 
-    private def mkArray(size: Int): Array[Unit] = {
-      val newelems = new Array[Unit](size)
-      if (this.size > 0) Array.copy(elems, 0, newelems, 0, this.size)
-      newelems
-    }
-
-    private def resize(size: Int) {
-      elems = mkArray(size)
-      capacity = size
-    }
-
-    override def sizeHint(size: Int) {
-      if (capacity < size) resize(size)
-    }
-
-    private def ensureSize(size: Int) {
-      if (capacity < size || capacity == 0) {
-        var newsize = if (capacity == 0) 16 else capacity * 2
-        while (newsize < size) newsize *= 2
-        resize(newsize)
-      }
-    }
-
     def +=(elem: Unit): this.type = {
-      ensureSize(size + 1)
-      elems(size) = elem
       size += 1
       this
     }
 
-    override def ++=(xs: TraversableOnce[Unit]): this.type = xs match {
-      case xs: WrappedArray.ofUnit =>
-        ensureSize(this.size + xs.length)
-        Array.copy(xs.array, 0, elems, this.size, xs.length)
-        size += xs.length
-        this
-      case _ =>
-        super.++=(xs)
+    override def ++=(xs: TraversableOnce[Unit]): this.type = {
+      size += xs.size
+      this
     }
 
-    def clear() {
-      size = 0
-    }
+    def clear() { size = 0 }
 
     def result() = {
-      if (capacity != 0 && capacity == size) elems
-      else mkArray(size)
+      val ans = new Array[Unit](size)
+      var i = 0
+      while (i < size) { ans(i) = (); i += 1 }
+      ans
     }
 
     override def equals(other: Any): Boolean = other match {
-      case x: ofUnit => (size == x.size) && (elems == x.elems)
+      case x: ofUnit => (size == x.size)
       case _ => false
     }