0
# Scala Collection Compat
1

2
Scala Collection Compat is a compatibility library that makes Scala 2.13 APIs available on Scala 2.11 and 2.12, facilitating cross-building and migration to newer Scala versions. It provides backported collection types, enhanced collection methods, Java interoperability utilities, and resource management features.
3

4
## Package Information
5

6
- **Package Name**: org.scala-lang.modules:scala-collection-compat_2.12
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scala-lang.modules" %% "scala-collection-compat" % "2.13.0"`
10

11
## Core Imports
12

13
```scala
14
import scala.collection.compat._
15
```
16

17
This single import provides access to all compatibility features including:
18
- Extension methods for existing collections
19
- Backported collection types (ArraySeq, LazyList)
20
- Safe string parsing methods
21
- Collection factory improvements
22

23
## Basic Usage
24

25
```scala
26
import scala.collection.compat._
27

28
// Use 2.13-style collection operations on 2.11/2.12
29
val numbers = List(1, 2, 3, 4, 5)
30
numbers.to(Vector)  // Instead of numbers.to[Vector]
31

32
// Safe string parsing
33
val maybeInt: Option[Int] = "42".toIntOption
34
val maybeDouble: Option[Double] = "3.14".toDoubleOption
35

36
// Enhanced collection methods
37
val data = List(1, 2, 3, 4, 5)
38
val min = data.minOption  // Safe minimum without exceptions
39
val max = data.maxOption  // Safe maximum without exceptions
40

41
// Size comparison operations
42
if (data.sizeIs > 3) println("Large collection")
43

44
// Backported lazy list
45
val infinite = LazyList.from(1)
46
val first10 = infinite.take(10).toList
47
```
48

49
## Architecture
50

51
Scala Collection Compat is organized around several key components:
52

53
- **Cross-Version Compatibility**: Provides consistent APIs across Scala 2.11, 2.12, and 2.13 through conditional compilation
54
- **Extension Methods**: Implicit classes that extend existing collection and string types with new functionality
55
- **Backported Types**: Full implementations of Scala 2.13 collection types for older versions
56
- **Factory Pattern**: Unified collection creation patterns using Factory and BuildFrom abstractions
57
- **Resource Management**: Try-with-resources semantics through the Using utility
58
- **Java Interoperability**: Seamless conversion between Scala and Java collections
59

60
## Capabilities
61

62
### Collection Extensions
63

64
Enhanced methods for existing Scala collections including safe operations, size comparisons, and functional utilities. Provides 2.13-style APIs on older Scala versions.
65

66
```scala { .api }
67
// Extension methods available through import scala.collection.compat._
68
def minOption[B >: A](implicit ord: Ordering[B]): Option[A]
69
def maxOption[B >: A](implicit ord: Ordering[B]): Option[A]
70
def sizeCompare(otherSize: Int): Int
71
def sizeIs: SizeCompareOps
72
def distinctBy[B](f: A => B): Collection[A]
73
def groupMap[K, B](key: A => K)(f: A => B): Map[K, Collection[B]]
74
```
75

76
[Collection Extensions](./collection-extensions.md)
77

78
### Backported Collections
79

80
Complete implementations of Scala 2.13 collection types for use on Scala 2.11 and 2.12, including ArraySeq and LazyList with full feature parity.
81

82
```scala { .api }
83
object ArraySeq {
84
  def apply[T](elems: T*)(implicit elemTag: ClassTag[T]): ArraySeq[T]
85
  def from[T](source: TraversableOnce[T])(implicit elemTag: ClassTag[T]): ArraySeq[T]
86
  def unsafeWrapArray[T](x: Array[T]): ArraySeq[T]
87
}
88

89
object LazyList {
90
  def apply[A](elems: A*): LazyList[A]
91
  def from[A](coll: GenTraversableOnce[A]): LazyList[A]
92
  def iterate[A](start: => A)(f: A => A): LazyList[A]
93
  def continually[A](elem: => A): LazyList[A]
94
}
95
```
96

97
[Backported Collections](./backported-collections.md)
98

99
### String Parsing
100

101
Safe string parsing methods that return Option types instead of throwing exceptions, providing consistent parsing across all numeric types.
102

103
```scala { .api }
104
implicit class StringOps(s: String) {
105
  def toBooleanOption: Option[Boolean]
106
  def toByteOption: Option[Byte]
107
  def toShortOption: Option[Short]
108
  def toIntOption: Option[Int]
109
  def toLongOption: Option[Long]
110
  def toFloatOption: Option[Float]
111
  def toDoubleOption: Option[Double]
112
}
113
```
114

115
[String Parsing](./string-parsing.md)
116

117
### Java Collection Conversion
118

119
Utilities for converting between Scala and Java collections with both implicit and explicit conversion methods.
120

121
```scala { .api }
122
import scala.jdk.CollectionConverters._
123
// Implicit conversions available through .asScala/.asJava extension methods
124

125
import scala.jdk.javaapi.CollectionConverters
126
// Explicit conversion methods for Java interop
127
def asScala[A](c: ju.Collection[A]): Iterable[A]
128
def asJava[A](i: Iterable[A]): jl.Iterable[A]
129
```
130

131
[Java Collection Conversion](./java-conversion.md)
132

133
### Resource Management
134

135
Automatic resource management with try-with-resources semantics through the Using utility, supporting single and multiple resource management.
136

137
```scala { .api }
138
object Using {
139
  def apply[R: Releasable, A](resource: => R)(f: R => A): Try[A]
140
  def resource[R, A](resource: R)(body: R => A)(implicit releasable: Releasable[R]): A
141
  def resources[R1: Releasable, R2: Releasable, A](r1: R1, r2: => R2)(body: (R1, R2) => A): A
142
}
143

144
trait Releasable[-R] {
145
  def release(resource: R): Unit
146
}
147
```
148

149
[Resource Management](./resource-management.md)
150

151
### Utility Features
152

153
Additional utilities including chaining operations, annotations for cross-compilation, and enhanced regex functionality.
154

155
```scala { .api }
156
final class ChainingOps[A](self: A) {
157
  def tap[U](f: A => U): A
158
  def pipe[B](f: A => B): B
159
}
160

161
class nowarn(value: String = "")
162
final class unused
163

164
implicit class RegexOps(regex: Regex) {
165
  def matches(source: CharSequence): Boolean
166
}
167
```
168

169
[Utility Features](./utility-features.md)
170

171
## Types
172

173
### Core Type Aliases
174

175
```scala { .api }
176
type IterableOnce[+X] = scala.collection.TraversableOnce[X]  // 2.11/2.12
177
type Factory[-A, +C] = CanBuildFrom[Nothing, A, C]           // 2.11/2.12
178
type BuildFrom[-From, -A, +C] = /* implementation */         // 2.11/2.12
179

180
// On Scala 2.13, these are aliases to standard library types
181
type Factory[-A, +C] = scala.collection.Factory[A, C]       // 2.13
182
type BuildFrom[-From, -A, +C] = scala.collection.BuildFrom[From, A, C]  // 2.13
183
```
184

185
### Collection Building
186

187
```scala { .api }
188
trait BuildFrom[-From, -A, +C] {
189
  def fromSpecific(from: From)(it: IterableOnce[A]): C
190
  def newBuilder(from: From): mutable.Builder[A, C]
191
}
192

193
trait Factory[-A, +C] {
194
  def fromSpecific(it: IterableOnce[A]): C
195
  def newBuilder: mutable.Builder[A, C]
196
}
197
```