0
# Scala Collection Compat
1

2
Scala Collection Compat provides Scala 2.13/3.0 collection APIs as backports for Scala 2.11 and 2.12, enabling cross-compilation by bridging API differences between Scala versions. It includes backported collection types, new collection methods, string parsing utilities, and Java interoperability features.
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" % "<version>"`
10

11
## Core Imports
12

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

17
Additional specialized imports:
18

19
```scala
20
import scala.jdk.CollectionConverters._
21
import scala.jdk.OptionConverters._
22
import scala.util.chaining._
23
import scala.util.Using  // For resource management (Scala 2.11 only)
24
```
25

26
## Basic Usage
27

28
```scala
29
import scala.collection.compat._
30

31
// Safe string parsing (returns Option types)
32
val num = "42".toIntOption  // Some(42)
33
val bad = "abc".toIntOption  // None
34

35
// New collection methods
36
val numbers = List(1, 2, 3, 4, 5)
37
val maxValue = numbers.maxOption  // Some(5)
38
val minValue = List.empty[Int].minOption  // None
39

40
// Method chaining
41
import scala.util.chaining._
42
val result = List(1, 2, 3)
43
  .tap(println)  // prints List(1, 2, 3) for debugging
44
  .pipe(_.sum)   // transforms to sum: 6
45

46
// Backported collections
47
import scala.collection.compat.immutable._
48
val lazyList = LazyList.from(1)  // infinite lazy sequence
49
val arraySeq = ArraySeq(1, 2, 3)  // immutable array-backed sequence
50
```
51

52
## Architecture
53

54
The library provides different implementations based on Scala version:
55
- **Scala 2.11/2.12**: Full compatibility implementations with extension methods
56
- **Scala 2.13/3.0**: Lightweight type aliases and empty package objects
57

58
Key design patterns:
59
- Extension methods via implicit classes for adding functionality to existing types
60
- Type aliases for consistent naming across Scala versions
61
- Safe operations returning Option types instead of throwing exceptions
62

63
## Capabilities
64

65
### Collection Factory System
66

67
Unified factory system for creating collections across Scala versions.
68

69
```scala { .api }
70
type Factory[-A, +C] = CanBuildFrom[Nothing, A, C]  // On 2.11/2.12
71

72
trait BuildFrom[-From, -A, +C] {
73
  def fromSpecific(from: From)(it: IterableOnce[A]): C
74
  def newBuilder(from: From): mutable.Builder[A, C]
75
}
76
```
77

78
[Collection Factories](./collection-factories.md)
79

80
### String Parsing Extensions
81

82
Safe parsing methods that return Option types instead of throwing exceptions.
83

84
```scala { .api }
85
implicit class StringOps(s: String) {
86
  def toBooleanOption: Option[Boolean]
87
  def toByteOption: Option[Byte]
88
  def toShortOption: Option[Short]
89
  def toIntOption: Option[Int]
90
  def toLongOption: Option[Long]
91
  def toFloatOption: Option[Float]
92
  def toDoubleOption: Option[Double]
93
}
94
```
95

96
[String Parsing](./string-parsing.md)
97

98
### Collection Extension Methods
99

100
Enhanced collection operations including safe min/max, method chaining, and advanced transformations.
101

102
```scala { .api }
103
implicit class TraversableOnceExtensionMethods[A](self: TraversableOnce[A]) {
104
  def minOption[B >: A](implicit ord: Ordering[B]): Option[A]
105
  def maxOption[B >: A](implicit ord: Ordering[B]): Option[A]
106
  def minByOption[B](f: A => B)(implicit cmp: Ordering[B]): Option[A]
107
  def maxByOption[B](f: A => B)(implicit cmp: Ordering[B]): Option[A]
108
}
109

110
implicit class TraversableLikeExtensionMethods[A, Repr](self: GenTraversableLike[A, Repr]) {
111
  def tapEach[U](f: A => U)(implicit bf: CanBuildFrom[Repr, A, Repr]): Repr
112
  def partitionMap[A1, A2, That, Repr1, Repr2](f: A => Either[A1, A2]): (Repr1, Repr2)
113
  def groupMap[K, B, That](key: A => K)(f: A => B): Map[K, That]
114
  def groupMapReduce[K, B](key: A => K)(f: A => B)(reduce: (B, B) => B): Map[K, B]
115
  def distinctBy[B, That](f: A => B): That
116
}
117
```
118

119
[Collection Extensions](./collection-extensions.md)
120

121
### Backported Collection Types
122

123
Scala 2.13 collection types made available on earlier versions.
124

125
```scala { .api }
126
// LazyList - replacement for Stream
127
final class LazyList[+A] extends AbstractSeq[A] with LinearSeq[A] {
128
  def head: A
129
  def tail: LazyList[A]
130
  def isEmpty: Boolean
131
  def force: this.type
132
  def knownSize: Int
133
}
134

135
object LazyList {
136
  def from[A](coll: GenTraversableOnce[A]): LazyList[A]
137
  def iterate[A](start: => A)(f: A => A): LazyList[A]
138
  def continually[A](elem: => A): LazyList[A]
139
  def unfold[A, S](init: S)(f: S => Option[(A, S)]): LazyList[A]
140
}
141

142
// ArraySeq - immutable array-backed sequence  
143
abstract class ArraySeq[+T] extends AbstractSeq[T] with IndexedSeq[T] {
144
  def length: Int
145
  def apply(index: Int): T
146
  def unsafeArray: Array[T]
147
}
148

149
object ArraySeq {
150
  def apply[T](elems: T*)(implicit elemTag: ClassTag[T]): ArraySeq[T]
151
  def unsafeWrapArray[T](x: Array[T]): ArraySeq[T]
152
  def empty[T <: AnyRef]: ArraySeq[T]
153
}
154
```
155

156
[Backported Collections](./backported-collections.md)
157

158
### Map Extension Methods
159

160
Enhanced map operations for both immutable and mutable maps.
161

162
```scala { .api }
163
implicit class MapExtensionMethods[K, V](self: Map[K, V]) {
164
  def foreachEntry[U](f: (K, V) => U): Unit
165
}
166

167
implicit class ImmutableMapExtensionMethods[K, V](self: immutable.Map[K, V]) {
168
  def updatedWith[V1 >: V](key: K)(remappingFunction: Option[V] => Option[V1]): Map[K, V1]
169
}
170

171
implicit class MutableMapExtensionMethods[K, V](self: mutable.Map[K, V]) {
172
  def updateWith(key: K)(remappingFunction: Option[V] => Option[V]): Option[V]
173
}
174
```
175

176
[Map Extensions](./map-extensions.md)
177

178
### Java Collection Interoperability
179

180
Seamless conversion between Scala and Java collections.
181

182
```scala { .api }
183
object CollectionConverters extends DecorateAsJava with DecorateAsScala
184
```
185

186
[Java Interop](./java-interop.md)
187

188
### Method Chaining Operations
189

190
Utility methods for functional programming patterns and debugging.
191

192
```scala { .api }
193
final class ChainingOps[A](private val self: A) {
194
  def tap[U](f: A => U): A  // Apply function for side effects, return original
195
  def pipe[B](f: A => B): B  // Transform value with function
196
}
197

198
trait ChainingSyntax {
199
  implicit def scalaUtilChainingOps[A](a: A): ChainingOps[A]
200
}
201

202
object chaining extends ChainingSyntax
203
```
204

205
[Method Chaining](./method-chaining.md)
206

207
### Iterator and Size Operations
208

209
Enhanced iterator methods and size comparison utilities.
210

211
```scala { .api }
212
implicit class IteratorExtensionMethods[A](self: Iterator[A]) {
213
  def nextOption(): Option[A]
214
  def sameElements[B >: A](that: TraversableOnce[B]): Boolean
215
  def tapEach[U](f: A => U): Iterator[A]
216
}
217

218
class SizeCompareOps(it: Traversable[_]) {
219
  def <(size: Int): Boolean
220
  def <=(size: Int): Boolean  
221
  def ==(size: Int): Boolean
222
  def !=(size: Int): Boolean
223
  def >=(size: Int): Boolean
224
  def >(size: Int): Boolean
225
}
226
```
227

228
[Iterator and Size Operations](./iterator-size-ops.md)
229

230
### Option to Java Optional Conversion
231

232
Utilities for converting between Scala `Option` and Java `Optional` types for seamless Java interoperability.
233

234
```scala { .api }
235
implicit class RichOption[A](o: Option[A]) extends AnyVal {
236
  def toJava: java.util.Optional[A]
237
}
238

239
implicit class RichOptional[A](o: java.util.Optional[A]) extends AnyVal {
240
  def toScala: Option[A]
241
}
242
```
243

244
[Option Converters](./option-converters.md)
245

246
### Resource Management
247

248
Automatic resource management utilities using the `Using` API for safely handling resources that need cleanup.
249

250
```scala { .api }
251
object Using {
252
  def apply[R: Releasable, A](resource: => R)(f: R => A): Try[A]
253
  
254
  object Manager {
255
    def apply[A](f: Manager => A): Try[A]
256
  }
257
}
258

259
trait Releasable[-R] {
260
  def release(resource: R): Unit
261
}
262
```
263

264
[Resource Management](./resource-management.md)
265

266
### Annotation Backports
267

268
Scala 2.13 annotations available on earlier versions.
269

270
```scala { .api }
271
class nowarn extends scala.annotation.StaticAnnotation
272
class unused extends scala.annotation.StaticAnnotation
273
```
274

275
[Annotation Backports](./annotation-backports.md)