Why is VectorBuilder in the package scala.collections.immutable?

Question

VectorBuilder defined in the same source file as Vector . Vector is immutable in the scala.collections.immutable package, so the builder is in the same package.

As far as I can tell, CanBuildFrom uses VectorBuilder as the default if the return type is not explicitly specified.

• Is there a reason why the linker does not exist in a separate file in a mutable package?
• Is the builder not intended for direct use? If so, which builder or buffer should be used to create Seq ?

Answer 1

VectorBuilder not intended for direct use. If you want to get a builder for Vector , you only need to call Vector.newBuilder[T] , which returns Builder[T, Vector[T]] (with the base instance, VectorBuilder ).

So, if you want the default builder to be used to create Seq , you only need to call Seq.newBuilder :

 scala> Seq(1,2,3) res0: Seq[Int] = List(1, 2, 3) scala> Seq.newBuilder[Int] res1: scala.collection.mutable.Builder[Int,Seq[Int]] = ListBuffer() scala> Seq.newBuilder[Int].result res2: Seq[Int] = List() 

The above shows that the default implementation of Seq is a list, and, logically, the default builder for Seq is actually mutable.ListBuffer .

ListBuffer more than just a List constructor, so it is in collection.mutable , while VectorBuilder not a Buffer , it cannot be used for anything other than building a Vector . This is probably why it is locally defined in Vector . I'm not sure why this is not private , I do not see links in it in the public Vector API. Maybe it should be (personal).

---

Just for reference, hidden magic doesn't happen with CanBuildFrom , it almost always goes through newBuilder above:

• If you do not specify the expected type of collection, as in Seq(1,2).map(_+1) , only the available CanBuildFrom appears from the companion object a Seq and has the type CanBuildFrom[Seq[_], T, Seq[T]] . This means that the result will also be Seq .

• Like most companion collection objects, the CanBuildFrom Seq instance provides only one thing: calling Seq.newBuilder (which is defined in GenTraversableFactory ...)

This is why CanBuildFrom for Vector uses VectorBuilder . For example, in this:

 scala> Vector(1,2,3).map(_+1) res12: scala.collection.immutable.Vector[Int] = Vector(2, 3, 4) 

Used builder:

 scala> implicitly[CanBuildFrom[Vector[Int], Int, Vector[Int]]].apply() res13: scala.collection.mutable.Builder[Int,Vector[Int]] = scala.collection.immutable.VectorBuilder@43efdf93 

Answer 2

There is no modified vector. By analogy with ListSetBuilder , the builder stays close to what he creates.

mutable.StringBuilder is abnormal as it is a frequently used type that is more first-class and tends to go through the API. (It gets a mention in the collection review and does not require import. In fact, it plays a role in this puzzle because it is subtly different from Java StringBuilder , but you may forget that you use it.)

VectorBuilder is an open API. newBuilder on companion objects is more associated with the factory and CanBuildFrom collection map. The review does not mention where it explains how to do things. I do not remember any fragments that suggest:

 (ListBuffer.newBuilder[String] += "hello" += "world").result.toList 

How you create Vector depends on what you do, but the review suggests factory methods on a companion. If you already have a collection (possibly non-strict), then toVector . How do you make any collection?

This is a good Vector over List Q & A for your Seq.

As an implementation detail, that the VectorPointer thing you see in scaladoc contains a big comment:

 // USED BY BUILDER 

Since VectorPointer is private[immutable] , the builder should remain there as a practical matter. This also suggests that there has been an opinion on what can be represented as an API.

In addition, Vector has a similar comment:

 // in principle, most members should be private. however, access privileges must // be carefully chosen to not prevent method inlining 

These comments suggest that access levels are not random.

This question presents an interesting opportunity to think about the design of the package. It is possible that the Scala collections are a Rorschach ink test showing great beauty and symmetry, and at the same time for a disturbed mind, there is a great imbalance in the universe. (Kind of a joke there.)