Merge pull request #4904 from Ichoran/reusable-builders

Clarified and expanded which Builders were reusable

15 files changed, 225 insertions, 108 deletions

diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala
index a65e25ed6e..98b91f7c84 100644
--- a/src/library/scala/collection/immutable/ListSet.scala
+++ b/src/library/scala/collection/immutable/ListSet.scala
@@ -12,7 +12,7 @@ package immutable
 
 import generic._
 import scala.annotation.tailrec
-import mutable.Builder
+import mutable.{Builder, ReusableBuilder}
 
 /** $factoryInfo
  *  @define Coll immutable.ListSet
@@ -32,8 +32,10 @@ object ListSet extends ImmutableSetFactory[ListSet] {
    *  a time to a list backed set puts the "squared" in N^2.  There is a
    *  temporary space cost, but it's improbable a list backed set could
    *  become large enough for this to matter given its pricy element lookup.
+   *
+   *  This builder is reusable.
    */
-  class ListSetBuilder[Elem](initial: ListSet[Elem]) extends Builder[Elem, ListSet[Elem]] {
+  class ListSetBuilder[Elem](initial: ListSet[Elem]) extends ReusableBuilder[Elem, ListSet[Elem]] {
     def this() = this(empty[Elem])
     protected val elems = (new mutable.ListBuffer[Elem] ++= initial).reverse
     protected val seen  = new mutable.HashSet[Elem] ++= initial
diff --git a/src/library/scala/collection/immutable/Vector.scala b/src/library/scala/collection/immutable/Vector.scala
index cd2d3f843b..754196e6c1 100644
--- a/src/library/scala/collection/immutable/Vector.scala
+++ b/src/library/scala/collection/immutable/Vector.scala
@@ -13,7 +13,7 @@ package immutable
 import scala.annotation.unchecked.uncheckedVariance
 import scala.compat.Platform
 import scala.collection.generic._
-import scala.collection.mutable.Builder
+import scala.collection.mutable.{Builder, ReusableBuilder}
 import scala.collection.parallel.immutable.ParVector
 
 /** Companion object to the Vector class
@@ -704,8 +704,8 @@ extends AbstractIterator[A]
   }
 }
 
-
-final class VectorBuilder[A]() extends Builder[A,Vector[A]] with VectorPointer[A @uncheckedVariance] {
+/** A class to build instances of `Vector`.  This builder is reusable. */
+final class VectorBuilder[A]() extends ReusableBuilder[A,Vector[A]] with VectorPointer[A @uncheckedVariance] {
 
   // possible alternative: start with display0 = null, blockIndex = -32, lo = 32
   // to avoid allocating initial array if the result will be empty anyways
diff --git a/src/library/scala/collection/mutable/AnyRefMap.scala b/src/library/scala/collection/mutable/AnyRefMap.scala
index af7600ad3d..2ed5bbea60 100644
--- a/src/library/scala/collection/mutable/AnyRefMap.scala
+++ b/src/library/scala/collection/mutable/AnyRefMap.scala
@@ -427,7 +427,11 @@ object AnyRefMap {
       def apply(): AnyRefMapBuilder[J, U] = new AnyRefMapBuilder[J, U]
     }
 
-  final class AnyRefMapBuilder[K <: AnyRef, V] extends Builder[(K, V), AnyRefMap[K, V]] {
+  /** A builder for instances of `AnyRefMap`.
+   *
+   *  This builder can be reused to create multiple instances.
+   */
+  final class AnyRefMapBuilder[K <: AnyRef, V] extends ReusableBuilder[(K, V), AnyRefMap[K, V]] {
     private[collection] var elems: AnyRefMap[K, V] = new AnyRefMap[K, V]
     def +=(entry: (K, V)): this.type = {
       elems += entry
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
     }
 
diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index 75560580cc..8d6a0ec69d 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -18,6 +18,14 @@ import generic._
  *  elements to the builder with `+=` and then converting to the required
  *  collection type with `result`.
  *
+ *  One cannot assume that a single `Builder` can build more than one
+ *  instance of the desired collection.  Particular subclasses may allow
+ *  such behavior.  Otherwise, `result` should be treated as a terminal
+ *  operation: after it is called, no further methods should be called on
+ *  the builder.  Extend the [[collection.mutable.ReusableBuilder]] trait
+ *  instead of `Builder` for builders that may be reused to build multiple
+ *  instances.
+ *
  *  @tparam  Elem  the type of elements that get added to the builder.
  *  @tparam  To    the type of collection that it produced.
  *
@@ -36,8 +44,10 @@ trait Builder[-Elem, +To] extends Growable[Elem] {
    */
   def clear()
 
-  /** Produces a collection from the added elements.
-   *  The builder's contents are undefined after this operation.
+  /** Produces a collection from the added elements.  This is a terminal operation:
+   *  the builder's contents are undefined after this operation, and no further
+   *  methods should be called.
+   *  
    *  @return a collection containing the elements added to this builder.
    */
   def result(): To
@@ -112,6 +122,8 @@ trait Builder[-Elem, +To] extends Growable[Elem] {
    *  @tparam NewTo the type of collection returned by `f`.
    *  @return a new builder which is the same as the current builder except
    *          that a transformation function is applied to this builder's result.
+   *
+   *  @note The original builder should no longer be used after `mapResult` is called.
    */
   def mapResult[NewTo](f: To => NewTo): Builder[Elem, NewTo] =
     new Builder[Elem, NewTo] with Proxy {
diff --git a/src/library/scala/collection/mutable/GrowingBuilder.scala b/src/library/scala/collection/mutable/GrowingBuilder.scala
index c4b5e546aa..27d554d98e 100644
--- a/src/library/scala/collection/mutable/GrowingBuilder.scala
+++ b/src/library/scala/collection/mutable/GrowingBuilder.scala
@@ -15,6 +15,8 @@ import generic._
 /** The canonical builder for collections that are growable, i.e. that support an
  *  efficient `+=` method which adds an element to the collection.
  *
+ *  GrowableBuilders can produce only a single instance of the collection they are growing.
+ *
  *  @author Paul Phillips
  *  @version 2.8
  *  @since 2.8
@@ -25,6 +27,6 @@ import generic._
 class GrowingBuilder[Elem, To <: Growable[Elem]](empty: To) extends Builder[Elem, To] {
   protected var elems: To = empty
   def +=(x: Elem): this.type = { elems += x; this }
-  def clear() { elems = empty }
+  def clear() { empty.clear }
   def result: To = elems
 }
diff --git a/src/library/scala/collection/mutable/LazyBuilder.scala b/src/library/scala/collection/mutable/LazyBuilder.scala
index ebee38b77f..f0a5e6971a 100644
--- a/src/library/scala/collection/mutable/LazyBuilder.scala
+++ b/src/library/scala/collection/mutable/LazyBuilder.scala
@@ -13,12 +13,14 @@ package mutable
 /** A builder that constructs its result lazily. Iterators or iterables to
  *  be added to this builder with `++=` are not evaluated until `result` is called.
  *
+ *  This builder can be reused.
+ *
  *  @since 2.8
  *
  *  @tparam Elem    type of the elements for this builder.
  *  @tparam To      type of the collection this builder builds.
  */
-abstract class LazyBuilder[Elem, +To] extends Builder[Elem, To] {
+abstract class LazyBuilder[Elem, +To] extends ReusableBuilder[Elem, To] {
   /** The different segments of elements to be added to the builder, represented as iterators */
   protected var parts = new ListBuffer[TraversableOnce[Elem]]
   def +=(x: Elem): this.type = { parts += List(x); this }
diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala
index 0a483ceb86..02fcced3ac 100644
--- a/src/library/scala/collection/mutable/ListBuffer.scala
+++ b/src/library/scala/collection/mutable/ListBuffer.scala
@@ -46,7 +46,7 @@ final class ListBuffer[A]
          with Buffer[A]
          with GenericTraversableTemplate[A, ListBuffer]
          with BufferLike[A, ListBuffer[A]]
-         with Builder[A, List[A]]
+         with ReusableBuilder[A, List[A]]
          with SeqForwarder[A]
          with Serializable
 {
@@ -297,6 +297,10 @@ final class ListBuffer[A]
 
 // Implementation of abstract method in Builder
 
+  /** Returns the accumulated `List`.
+   *
+   *  This method may be called multiple times to obtain snapshots of the list in different stages of construction.
+   */
   def result: List[A] = toList
 
   /** Converts this buffer to a list. Takes constant time. The buffer is
diff --git a/src/library/scala/collection/mutable/LongMap.scala b/src/library/scala/collection/mutable/LongMap.scala
index f39a6ba634..ecbb1952af 100644
--- a/src/library/scala/collection/mutable/LongMap.scala
+++ b/src/library/scala/collection/mutable/LongMap.scala
@@ -519,7 +519,11 @@ object LongMap {
       def apply(): LongMapBuilder[U] = new LongMapBuilder[U]
     }
 
-  final class LongMapBuilder[V] extends Builder[(Long, V), LongMap[V]] {
+  /** A builder for instances of `LongMap`.
+   *
+   *  This builder can be reused to create multiple instances.
+   */
+  final class LongMapBuilder[V] extends ReusableBuilder[(Long, V), LongMap[V]] {
     private[collection] var elems: LongMap[V] = new LongMap[V]
     def +=(entry: (Long, V)): this.type = {
       elems += entry
diff --git a/src/library/scala/collection/mutable/MapBuilder.scala b/src/library/scala/collection/mutable/MapBuilder.scala
index a5a6b12ea9..cfc3079f41 100644
--- a/src/library/scala/collection/mutable/MapBuilder.scala
+++ b/src/library/scala/collection/mutable/MapBuilder.scala
@@ -23,7 +23,7 @@ package mutable
  *  @since 2.8
  */
 class MapBuilder[A, B, Coll <: scala.collection.GenMap[A, B] with scala.collection.GenMapLike[A, B, Coll]](empty: Coll)
-extends Builder[(A, B), Coll] {
+extends ReusableBuilder[(A, B), Coll] {
   protected var elems: Coll = empty
   def +=(x: (A, B)): this.type = {
     elems = (elems + x).asInstanceOf[Coll]
diff --git a/src/library/scala/collection/mutable/ReusableBuilder.scala b/src/library/scala/collection/mutable/ReusableBuilder.scala
new file mode 100644
index 0000000000..caab3071b6
--- /dev/null
+++ b/src/library/scala/collection/mutable/ReusableBuilder.scala
@@ -0,0 +1,51 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2016, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
+package scala
+package collection
+package mutable
+
+import generic._
+
+/** `ReusableBuilder` is a marker trait that indicates that a `Builder`
+ *  can be reused to build more than one instance of a collection.  In
+ *  particular, calling `result` followed by `clear` will produce a
+ *  collection and reset the builder to begin building a new collection
+ *  of the same type.
+ *
+ *  It is up to subclasses to implement this behavior, and to document any
+ *  other behavior that varies from standard `ReusableBuilder` usage
+ *  (e.g. operations being well-defined after a call to `result`, or allowing
+ *  multiple calls to result to obtain different snapshots of a collection under
+ *  construction).
+ *
+ *  @tparam  Elem  the type of elements that get added to the builder.
+ *  @tparam  To    the type of collection that it produced.
+ *
+ *  @since 2.12
+ */
+trait ReusableBuilder[-Elem, +To] extends Builder[Elem, To] {
+  /** Clears the contents of this builder.
+   *  After execution of this method, the builder will contain no elements.
+   *
+   *  If executed immediately after a call to `result`, this allows a new
+   *  instance of the same type of collection to be built.
+   */
+  override def clear(): Unit    // Note: overriding for scaladoc only!
+
+  /** Produces a collection from the added elements.
+   *
+   *  After a call to `result`, the behavior of all other methods is undefined
+   *  save for `clear`.  If `clear` is called, then the builder is reset and
+   *  may be used to build another instance.
+   *  
+   *  @return a collection containing the elements added to this builder.
+   */
+  override def result(): To    // Note: overriding for scaladoc only!
+}
diff --git a/src/library/scala/collection/mutable/SetBuilder.scala b/src/library/scala/collection/mutable/SetBuilder.scala
index 01bfdc96ed..5d1e9ffc3a 100644
--- a/src/library/scala/collection/mutable/SetBuilder.scala
+++ b/src/library/scala/collection/mutable/SetBuilder.scala
@@ -17,7 +17,9 @@ package mutable
  *  @param empty   The empty element of the collection.
  *  @since 2.8
  */
-class SetBuilder[A, Coll <: scala.collection.Set[A] with scala.collection.SetLike[A, Coll]](empty: Coll) extends Builder[A, Coll] {
+class SetBuilder[A, Coll <: scala.collection.Set[A]
+with scala.collection.SetLike[A, Coll]](empty: Coll)
+extends ReusableBuilder[A, Coll] {
   protected var elems: Coll = empty
   def +=(x: A): this.type = { elems = elems + x; this }
   def clear() { elems = empty }
diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala
index c56d40786e..b5b9498374 100644
--- a/src/library/scala/collection/mutable/StringBuilder.scala
+++ b/src/library/scala/collection/mutable/StringBuilder.scala
@@ -33,7 +33,7 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
          with java.lang.CharSequence
          with IndexedSeq[Char]
          with StringLike[StringBuilder]
-         with Builder[Char, String]
+         with ReusableBuilder[Char, String]
          with Serializable {
 
   override protected[this] def thisCollection: StringBuilder = this
@@ -435,7 +435,11 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
    */
   override def mkString = toString
 
-  /** Returns the result of this Builder (a String)
+  /** Returns the result of this Builder (a String).
+   *
+   *  If this method is called multiple times, each call will result in a snapshot of the buffer at that point in time.
+   *  In particular, a `StringBuilder` can be used to build multiple independent strings by emptying the buffer with `clear`
+   *  after each call to `result`.
    *
    *  @return  the string assembled by this StringBuilder
    */
diff --git a/src/library/scala/collection/mutable/WrappedArrayBuilder.scala b/src/library/scala/collection/mutable/WrappedArrayBuilder.scala
index bfe95a11ab..c4781321d7 100644
--- a/src/library/scala/collection/mutable/WrappedArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/WrappedArrayBuilder.scala
@@ -17,12 +17,14 @@ import scala.runtime.ScalaRunTime._
 
 /** A builder class for arrays.
  *
+ *  This builder can be reused.
+ *
  *  @tparam A   type of elements that can be added to this builder.
  *  @param tag  class tag for objects of type `A`.
  *
  *  @since 2.8
  */
-class WrappedArrayBuilder[A](tag: ClassTag[A]) extends Builder[A, WrappedArray[A]] {
+class WrappedArrayBuilder[A](tag: ClassTag[A]) extends ReusableBuilder[A, WrappedArray[A]] {
 
   @deprecated("use tag instead", "2.10.0")
   val manifest: ClassTag[A] = tag
@@ -73,12 +75,13 @@ class WrappedArrayBuilder[A](tag: ClassTag[A]) extends Builder[A, WrappedArray[A
     this
   }
 
-  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)
   }
 
diff --git a/test/junit/scala/collection/ReusableBuildersTest.scala b/test/junit/scala/collection/ReusableBuildersTest.scala
new file mode 100644
index 0000000000..8dd1a37adf
--- /dev/null
+++ b/test/junit/scala/collection/ReusableBuildersTest.scala
@@ -0,0 +1,48 @@
+package scala.collection
+
+import org.junit.runner.RunWith
+import org.junit.runners.JUnit4
+import org.junit.Test
+
+/* Tests various maps by making sure they all agree on the same answers. */
+@RunWith(classOf[JUnit4])
+class ReusableBuildersTest {
+  // GrowingBuilders are NOT reusable but can clear themselves
+  @Test
+  def test_SI8648() {
+    val b = collection.mutable.HashSet.newBuilder[Int]
+    b += 3
+    b.clear
+    assert(!b.isInstanceOf[collection.mutable.ReusableBuilder[_,_]])
+    assert(b.isInstanceOf[collection.mutable.GrowingBuilder[_,_]])
+    assert(b.result == Set[Int]())
+  }
+
+  // ArrayBuilders ARE reusable, regardless of whether they returned their internal array or not
+  @Test
+  def test_SI9564() {
+    val b = Array.newBuilder[Float]
+    b += 3f
+    val three = b.result
+    b.clear
+    b ++= (1 to 16).map(_.toFloat)
+    val sixteen = b.result
+    b.clear
+    b += 0f
+    val zero = b.result
+    assert(b.isInstanceOf[collection.mutable.ReusableBuilder[_,_]])
+    assert(three.toList == 3 :: Nil)
+    assert(sixteen.toList == (1 to 16))
+    assert(zero.toList == 0 :: Nil)
+  }
+
+  @Test
+  def test_reusability() {
+    val bl = List.newBuilder[String]
+    val bv = Vector.newBuilder[String]
+    val ba = collection.mutable.ArrayBuffer.newBuilder[String]
+    assert(bl.isInstanceOf[collection.mutable.ReusableBuilder[_, _]])
+    assert(bv.isInstanceOf[collection.mutable.ReusableBuilder[_, _]])
+    assert(!ba.isInstanceOf[collection.mutable.ReusableBuilder[_, _]])
+  }
+}