0
# Collection Factories
1

2
The collection factory system provides a unified way to create collections across different Scala versions, abstracting away the differences between Scala 2.11/2.12 and 2.13/3.0.
3

4
## Core Types
5

6
### Factory Type Alias
7

8
```scala { .api }
9
type Factory[-A, +C] = CanBuildFrom[Nothing, A, C]
10
```
11

12
A factory that builds a collection of type `C` with elements of type `A`. On Scala 2.11/2.12, this is implemented as a type alias for `CanBuildFrom`. On Scala 2.13+, it aliases `scala.collection.Factory`.
13

14
### BuildFrom Trait
15

16
```scala { .api }
17
trait BuildFrom[-From, -A, +C] extends Any {
18
  def fromSpecific(from: From)(it: IterableOnce[A]): C
19
  def newBuilder(from: From): mutable.Builder[A, C]
20
  
21
  @deprecated("Use newBuilder() instead of apply()", "2.13.0")
22
  @inline def apply(from: From): mutable.Builder[A, C] = newBuilder(from)
23
}
24

25
object BuildFrom {
26
  // Implicit instance derived from an implicit CanBuildFrom instance
27
  implicit def fromCanBuildFrom[From, A, C](
28
      implicit cbf: CanBuildFrom[From, A, C]): BuildFrom[From, A, C]
29
      
30
  // Implicit conversion derived from an implicit conversion to CanBuildFrom  
31
  implicit def fromCanBuildFromConversion[X, From, A, C](x: X)(
32
      implicit toCanBuildFrom: X => CanBuildFrom[From, A, C]): BuildFrom[From, A, C]
33
}
34
```
35

36
Builds a collection of type `C` from elements of type `A` when a source collection of type `From` is available. This trait bridges the API differences between Scala versions by providing automatic conversions from `CanBuildFrom` instances.
37

38
## Extension Methods
39

40
### FactoryOps
41

42
```scala { .api }
43
implicit class FactoryOps[-A, +C](private val factory: Factory[A, C]) {
44
  def fromSpecific(it: TraversableOnce[A]): C
45
  def newBuilder: mutable.Builder[A, C]
46
}
47
```
48

49
Extension methods for the `Factory` type:
50

51
- **fromSpecific**: Create a collection from a `TraversableOnce` of elements
52
- **newBuilder**: Get a new builder for the collection type
53

54
### IterableFactoryExtensionMethods
55

56
```scala { .api }
57
implicit class IterableFactoryExtensionMethods[CC[X] <: GenTraversable[X]](
58
    private val fact: GenericCompanion[CC]) {
59
  def from[A](source: TraversableOnce[A]): CC[A]
60
}
61
```
62

63
Extension methods for generic collection companions.
64

65
### MapFactoryExtensionMethods
66

67
```scala { .api }
68
implicit class MapFactoryExtensionMethods[CC[A, B] <: Map[A, B] with MapLike[A, B, CC[A, B]]](
69
    private val fact: MapFactory[CC]) {
70
  def from[K, V](source: TraversableOnce[(K, V)]): CC[K, V]
71
}
72
```
73

74
Extension methods for map factory companions.
75

76
### BitSetFactoryExtensionMethods
77

78
```scala { .api }
79
implicit class BitSetFactoryExtensionMethods[C <: BitSet with BitSetLike[C]](
80
    private val fact: BitSetFactory[C]) {
81
  def fromSpecific(source: TraversableOnce[Int]): C
82
}
83
```
84

85
Extension methods for BitSet factory companions.
86

87
## Collection-Specific Factory Extensions
88

89
### Array Extensions
90

91
```scala { .api }
92
final class ArrayExtensions(private val fact: Array.type) extends AnyVal {
93
  def from[A: ClassTag](source: TraversableOnce[A]): Array[A]
94
}
95
```
96

97
### Immutable Map Extensions
98

99
```scala { .api }
100
class ImmutableSortedMapExtensions(private val fact: immutable.SortedMap.type) extends AnyVal {
101
  def from[K: Ordering, V](source: TraversableOnce[(K, V)]): immutable.SortedMap[K, V]
102
}
103

104
class ImmutableListMapExtensions(private val fact: immutable.ListMap.type) extends AnyVal {
105
  def from[K, V](source: TraversableOnce[(K, V)]): immutable.ListMap[K, V]
106
}
107

108
class ImmutableHashMapExtensions(private val fact: immutable.HashMap.type) extends AnyVal {
109
  def from[K, V](source: TraversableOnce[(K, V)]): immutable.HashMap[K, V]
110
}
111

112
class ImmutableTreeMapExtensions(private val fact: immutable.TreeMap.type) extends AnyVal {
113
  def from[K: Ordering, V](source: TraversableOnce[(K, V)]): immutable.TreeMap[K, V]
114
}
115

116
class ImmutableIntMapExtensions(private val fact: immutable.IntMap.type) extends AnyVal {
117
  def from[V](source: TraversableOnce[(Int, V)]): immutable.IntMap[V]
118
}
119

120
class ImmutableLongMapExtensions(private val fact: immutable.LongMap.type) extends AnyVal {
121
  def from[V](source: TraversableOnce[(Long, V)]): immutable.LongMap[V]
122
}
123
```
124

125
### Mutable Map Extensions
126

127
```scala { .api }
128
class MutableLongMapExtensions(private val fact: mutable.LongMap.type) extends AnyVal {
129
  def from[V](source: TraversableOnce[(Long, V)]): mutable.LongMap[V]
130
}
131

132
class MutableHashMapExtensions(private val fact: mutable.HashMap.type) extends AnyVal {
133
  def from[K, V](source: TraversableOnce[(K, V)]): mutable.HashMap[K, V]
134
}
135

136
class MutableListMapExtensions(private val fact: mutable.ListMap.type) extends AnyVal {
137
  def from[K, V](source: TraversableOnce[(K, V)]): mutable.ListMap[K, V]
138
}
139

140
class MutableMapExtensions(private val fact: mutable.Map.type) extends AnyVal {
141
  def from[K, V](source: TraversableOnce[(K, V)]): mutable.Map[K, V]
142
}
143
```
144

145
## Usage Examples
146

147
### Creating Collections from Iterables
148

149
```scala
150
import scala.collection.compat._
151

152
// Using factory extensions
153
val list = List.from(Array(1, 2, 3))
154
val set = Set.from(List(1, 2, 2, 3))
155
val map = Map.from(List("a" -> 1, "b" -> 2))
156

157
// Using Array extensions  
158
val array = Array.from(List(1, 2, 3))
159

160
// Using specialized map factories
161
val sortedMap = immutable.SortedMap.from(List("c" -> 3, "a" -> 1, "b" -> 2))
162
val hashMap = immutable.HashMap.from(List("x" -> 10, "y" -> 20))
163
```
164

165
### Working with Builders
166

167
```scala
168
import scala.collection.compat._
169

170
// Get a builder from factory
171
val listFactory: Factory[Int, List[Int]] = implicitly
172
val builder = listFactory.newBuilder
173
builder += 1
174
builder += 2
175
val result = builder.result()  // List(1, 2)
176

177
// Use fromSpecific for direct creation
178
val list2 = listFactory.fromSpecific(Array(3, 4, 5))  // List(3, 4, 5)
179
```
180

181
## Implementation Notes
182

183
- On Scala 2.11/2.12, factories are implemented using `CanBuildFrom`
184
- On Scala 2.13+, factories are type aliases to the native `Factory` type
185
- The `BuildFrom` trait provides forward compatibility for the 2.13 API
186
- Extension methods are added via implicit classes to avoid binary compatibility issues