0
# Scala Collection Compat
1
2
Scala 2.13 Collection Compatibility Library providing backported collection APIs and migration tools for cross-building projects. This library enables developers to use Scala 2.13 collection APIs in Scala 2.11 and 2.12 projects, facilitating smooth migration and cross-compilation.
3
4
## Package Information
5
6
- **Package Name**: scala-collection-compat
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scala-lang.modules" %% "scala-collection-compat" % "1.0.0"`
10
11
## Core Imports
12
13
```scala
14
import scala.collection.compat._
15
```
16
17
For specific collection types:
18
19
```scala
20
import scala.collection.compat.immutable.ArraySeq
21
import scala.collection.compat.{Factory, BuildFrom}
22
```
23
24
## Basic Usage
25
26
### Cross-Version Collection Operations
27
28
```scala
29
import scala.collection.compat._
30
31
// Using 2.13 syntax in 2.11/2.12
32
val list = List(1, 2, 3)
33
val vector = list.to(Vector) // Instead of list.to[Vector]
34
35
// Creating collections from existing data
36
val data = List(1, 2, 3, 4, 5)
37
val set = Set.from(data) // 2.13-style factory method
38
```
39
40
### ArraySeq Usage
41
42
```scala
43
import scala.collection.compat.immutable.ArraySeq
44
45
// Create from existing array
46
val array = Array(1, 2, 3, 4, 5)
47
val arraySeq = ArraySeq.unsafeWrapArray(array)
48
49
// Create using builder
50
val seq = ArraySeq(1, 2, 3, 4, 5)
51
println(seq(2)) // Efficient indexed access: 3
52
```
53
54
### Factory and BuildFrom Pattern
55
56
```scala
57
import scala.collection.compat._
58
59
def convertCollection[A, C](
60
data: TraversableOnce[A],
61
factory: Factory[A, C]
62
): C = {
63
factory.fromSpecific(data)
64
}
65
66
val numbers = List(1, 2, 3)
67
val vector = convertCollection(numbers, Vector)
68
val set = convertCollection(numbers, Set)
69
```
70
71
## Architecture
72
73
The library provides two main architectural components:
74
75
1. **Compatibility Layer**: Backports 2.13 collection APIs to 2.11/2.12 through implicit conversions and extension methods
76
2. **Migration Tools**: Scalafix rules for automated code transformation between collection API versions
77
78
The compatibility layer uses a version-specific design where different Scala versions have tailored implementations:
79
- **Scala 2.11/2.12**: Full compatibility implementation with custom types and extension methods
80
- **Scala 2.13**: Minimal type aliases to standard library components
81
82
## Capabilities
83
84
### Collection Factory Operations
85
86
Provides 2.13-style factory methods for creating collections from existing data sources.
87
88
```scala { .api }
89
// Factory type alias and operations
90
type Factory[-A, +C] = CanBuildFrom[Nothing, A, C]
91
92
implicit class FactoryOps[-A, +C](factory: Factory[A, C]) {
93
def fromSpecific(it: TraversableOnce[A]): C
94
def newBuilder: Builder[A, C]
95
}
96
```
97
98
[Collection Factory Operations](./factory-operations.md)
99
100
### Collection Extensions
101
102
Extension methods that add 2.13 collection functionality to 2.11/2.12 collections.
103
104
```scala { .api }
105
// Map factory extensions
106
implicit class MapFactoryExtensionMethods[CC[A, B] <: Map[A, B]](fact: MapFactory[CC]) {
107
def from[K, V](source: TraversableOnce[(K, V)]): CC[K, V]
108
}
109
110
// Iterator extensions
111
implicit class IteratorExtensionMethods[A](self: Iterator[A]) {
112
def sameElements[B >: A](that: TraversableOnce[B]): Boolean
113
def concat[B >: A](that: TraversableOnce[B]): TraversableOnce[B]
114
}
115
```
116
117
[Collection Extensions](./collection-extensions.md)
118
119
### ArraySeq Implementation
120
121
Immutable array-backed sequence with efficient indexed access and primitive specializations.
122
123
```scala { .api }
124
abstract class ArraySeq[+T] extends AbstractSeq[T] with IndexedSeq[T] {
125
def length: Int
126
def apply(index: Int): T
127
def unsafeArray: Array[T]
128
protected def elemTag: ClassTag[T]
129
}
130
131
object ArraySeq {
132
def unsafeWrapArray[T](x: Array[T]): ArraySeq[T]
133
def empty[T <: AnyRef]: ArraySeq[T]
134
}
135
```
136
137
[ArraySeq Implementation](./arrayseq.md)
138
139
### BuildFrom Abstraction
140
141
Cross-compilation abstraction for building collections with source context.
142
143
```scala { .api }
144
trait BuildFrom[-From, -A, +C] {
145
def fromSpecificIterable(from: From)(it: Iterable[A]): C
146
def newBuilder(from: From): Builder[A, C]
147
}
148
149
object BuildFrom {
150
implicit def fromCanBuildFrom[From, A, C](
151
implicit cbf: CanBuildFrom[From, A, C]
152
): BuildFrom[From, A, C]
153
}
154
```
155
156
[BuildFrom Abstraction](./buildfrom.md)
157
158
### Migration Tools
159
160
Scalafix rules for automated migration between collection API versions.
161
162
```scala { .api }
163
// Cross-compatible migration (for libraries)
164
class Collection213CrossCompat extends LegacySemanticRule
165
166
// Full upgrade migration (for applications)
167
class Collection213Upgrade extends LegacySemanticRule
168
```
169
170
[Migration Tools](./migration-tools.md)
171
172
## Type Definitions
173
174
### Core Type Aliases
175
176
```scala { .api }
177
type Factory[-A, +C] = CanBuildFrom[Nothing, A, C]
178
type IterableOnce[+X] = TraversableOnce[X]
179
```
180
181
### Core Implicit Conversions
182
183
```scala { .api }
184
// Generic companion to CanBuildFrom conversion
185
implicit def genericCompanionToCBF[A, CC[X] <: GenTraversable[X]](
186
fact: GenericCompanion[CC]
187
): CanBuildFrom[Any, A, CC[A]]
188
189
// Sorted set companion conversion
190
implicit def sortedSetCompanionToCBF[A: Ordering, CC[X] <: SortedSet[X]](
191
fact: SortedSetFactory[CC]
192
): CanBuildFrom[Any, A, CC[A]]
193
194
// Array companion conversion
195
implicit def arrayCompanionToCBF[A: ClassTag](
196
fact: Array.type
197
): CanBuildFrom[Any, A, Array[A]]
198
199
// Map factory conversions
200
implicit def mapFactoryToCBF[K, V, CC[A, B] <: Map[A, B]](
201
fact: MapFactory[CC]
202
): CanBuildFrom[Any, (K, V), CC[K, V]]
203
204
implicit def sortedMapFactoryToCBF[K: Ordering, V, CC[A, B] <: SortedMap[A, B]](
205
fact: SortedMapFactory[CC]
206
): CanBuildFrom[Any, (K, V), CC[K, V]]
207
208
// BitSet factory conversions
209
implicit def bitSetFactoryToCBF(
210
fact: BitSetFactory[BitSet]
211
): CanBuildFrom[Any, Int, BitSet]
212
213
implicit def immutableBitSetFactoryToCBF(
214
fact: BitSetFactory[immutable.BitSet]
215
): CanBuildFrom[Any, Int, ImmutableBitSetCC[Int]]
216
217
implicit def mutableBitSetFactoryToCBF(
218
fact: BitSetFactory[mutable.BitSet]
219
): CanBuildFrom[Any, Int, MutableBitSetCC[Int]]
220
```
221
222
### Extension Method Conversions
223
224
```scala { .api }
225
// Collection factory extensions
226
implicit def toIterableFactoryExtensionMethods[CC[X] <: GenTraversable[X]](
227
fact: GenericCompanion[CC]
228
): IterableFactoryExtensionMethods[CC]
229
230
implicit def toMapFactoryExtensionMethods[CC[A, B] <: Map[A, B]](
231
fact: MapFactory[CC]
232
): MapFactoryExtensionMethods[CC]
233
234
implicit def toBitSetFactoryExtensionMethods[C <: BitSet](
235
fact: BitSetFactory[C]
236
): BitSetFactoryExtensionMethods[C]
237
238
// Collection operation extensions
239
implicit def toStreamExtensionMethods[A](
240
stream: Stream[A]
241
): StreamExtensionMethods[A]
242
243
implicit def toSortedExtensionMethods[K, V <: Sorted[K, V]](
244
fact: Sorted[K, V]
245
): SortedExtensionMethods[K, V]
246
247
implicit def toIteratorExtensionMethods[A](
248
self: Iterator[A]
249
): IteratorExtensionMethods[A]
250
251
implicit def toTraversableExtensionMethods[A](
252
self: Traversable[A]
253
): TraversableExtensionMethods[A]
254
255
implicit def toTraversableOnceExtensionMethods[A](
256
self: TraversableOnce[A]
257
): TraversableOnceExtensionMethods[A]
258
```
259
260
### Version-Specific Types
261
262
**Scala 2.11/2.12:**
263
```scala { .api }
264
type Factory[-A, +C] = CanBuildFrom[Nothing, A, C]
265
type BuildFrom[-From, -A, +C] = scala.collection.compat.BuildFrom[From, A, C]
266
type IterableOnce[+X] = TraversableOnce[X]
267
```
268
269
**Scala 2.13:**
270
```scala { .api }
271
type Factory[-A, +C] = scala.collection.Factory[A, C]
272
type BuildFrom[-From, -A, +C] = scala.collection.BuildFrom[From, A, C]
273
type IterableOnce[+X] = scala.collection.IterableOnce[X]
274
```