0
# Collection Extensions
1

2
This document covers the extension methods that add 2.13 collection functionality to 2.11/2.12 collections.
3

4
## Iterator Extensions
5

6
### IteratorExtensionMethods
7

8
```scala { .api }
9
implicit class IteratorExtensionMethods[A](private val self: c.Iterator[A]) {
10
  /**
11
   * Tests whether this iterator contains the same elements as the given collection,
12
   * in the same order.
13
   */
14
  def sameElements[B >: A](that: c.TraversableOnce[B]): Boolean
15
  
16
  /**
17
   * Concatenates this iterator with the given collection, returning a TraversableOnce.
18
   */
19
  def concat[B >: A](that: c.TraversableOnce[B]): c.TraversableOnce[B]
20
}
21
```
22

23
## Traversable Extensions
24

25
### TraversableExtensionMethods
26

27
```scala { .api }
28
implicit class TraversableExtensionMethods[A](private val self: c.Traversable[A]) {
29
  /**
30
   * Gets the factory companion object for this traversable.
31
   */
32
  def iterableFactory: GenericCompanion[Traversable]
33
}
34
```
35

36
### TraversableOnceExtensionMethods
37

38
```scala { .api }
39
implicit class TraversableOnceExtensionMethods[A](private val self: c.TraversableOnce[A]) {
40
  /**
41
   * Creates an iterator from this TraversableOnce.
42
   */
43
  def iterator: Iterator[A]
44
}
45
```
46

47
## Stream Extensions
48

49
### StreamExtensionMethods
50

51
```scala { .api }
52
implicit class StreamExtensionMethods[A](private val stream: Stream[A]) {
53
  /**
54
   * Lazily appends all elements from the given collection to this stream.
55
   * The collection is evaluated lazily when the stream elements are accessed.
56
   */
57
  def lazyAppendedAll(as: => TraversableOnce[A]): Stream[A]
58
}
59
```
60

61
## Sorted Collection Extensions
62

63
### SortedExtensionMethods
64

65
```scala { .api }
66
class SortedExtensionMethods[K, T <: Sorted[K, T]](private val fact: Sorted[K, T]) {
67
  /**
68
   * Creates a view of this sorted collection containing all elements
69
   * with keys greater than or equal to the given key.
70
   */
71
  def rangeFrom(from: K): T
72
  
73
  /**
74
   * Creates a view of this sorted collection containing all elements
75
   * with keys less than or equal to the given key.
76
   */
77
  def rangeTo(to: K): T
78
  
79
  /**
80
   * Creates a view of this sorted collection containing all elements
81
   * with keys strictly less than the given key.
82
   */
83
  def rangeUntil(until: K): T
84
}
85
```
86

87
## Map Extensions
88

89
### Immutable Map Extensions
90

91
```scala { .api }
92
// SortedMap extensions
93
class ImmutableSortedMapExtensions(private val fact: immutable.SortedMap.type) {
94
  def from[K: Ordering, V](source: TraversableOnce[(K, V)]): immutable.SortedMap[K, V]
95
}
96

97
// ListMap extensions
98
class ImmutableListMapExtensions(private val fact: immutable.ListMap.type) {
99
  def from[K, V](source: TraversableOnce[(K, V)]): immutable.ListMap[K, V]
100
}
101

102
// HashMap extensions
103
class ImmutableHashMapExtensions(private val fact: immutable.HashMap.type) {
104
  def from[K, V](source: TraversableOnce[(K, V)]): immutable.HashMap[K, V]
105
}
106

107
// TreeMap extensions
108
class ImmutableTreeMapExtensions(private val fact: immutable.TreeMap.type) {
109
  def from[K: Ordering, V](source: TraversableOnce[(K, V)]): immutable.TreeMap[K, V]
110
}
111

112
// IntMap extensions
113
class ImmutableIntMapExtensions(private val fact: immutable.IntMap.type) {
114
  def from[V](source: TraversableOnce[(Int, V)]): immutable.IntMap[V]
115
}
116

117
// LongMap extensions
118
class ImmutableLongMapExtensions(private val fact: immutable.LongMap.type) {
119
  def from[V](source: TraversableOnce[(Long, V)]): immutable.LongMap[V]
120
}
121
```
122

123
### Mutable Map Extensions
124

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

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

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

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

147
### Scala 2.12 Specific Extensions
148

149
```scala { .api }
150
// TreeMap extensions (Scala 2.12 only)
151
class MutableTreeMapExtensions2(private val fact: mutable.TreeMap.type) {
152
  def from[K: Ordering, V](source: TraversableOnce[(K, V)]): mutable.TreeMap[K, V]
153
}
154

155
// SortedMap extensions (Scala 2.12 only)
156
class MutableSortedMapExtensions(private val fact: mutable.SortedMap.type) {
157
  def from[K: Ordering, V](source: TraversableOnce[(K, V)]): mutable.SortedMap[K, V]
158
}
159
```
160

161
## Implicit Conversions to Extensions
162

163
All extension classes are made available through implicit conversions:
164

165
```scala { .api }
166
// Iterator extensions
167
implicit def toIteratorExtensionMethods[A](self: Iterator[A]): IteratorExtensionMethods[A]
168

169
// Traversable extensions
170
implicit def toTraversableExtensionMethods[A](self: Traversable[A]): TraversableExtensionMethods[A]
171
implicit def toTraversableOnceExtensionMethods[A](self: TraversableOnce[A]): TraversableOnceExtensionMethods[A]
172

173
// Stream extensions
174
implicit def toStreamExtensionMethods[A](stream: Stream[A]): StreamExtensionMethods[A]
175

176
// Sorted extensions
177
implicit def toSortedExtensionMethods[K, V <: Sorted[K, V]](fact: Sorted[K, V]): SortedExtensionMethods[K, V]
178

179
// Map extensions
180
implicit def toImmutableSortedMapExtensions(fact: immutable.SortedMap.type): ImmutableSortedMapExtensions
181
implicit def toImmutableListMapExtensions(fact: immutable.ListMap.type): ImmutableListMapExtensions
182
implicit def toImmutableHashMapExtensions(fact: immutable.HashMap.type): ImmutableHashMapExtensions
183
implicit def toImmutableTreeMapExtensions(fact: immutable.TreeMap.type): ImmutableTreeMapExtensions
184
implicit def toImmutableIntMapExtensions(fact: immutable.IntMap.type): ImmutableIntMapExtensions
185
implicit def toImmutableLongMapExtensions(fact: immutable.LongMap.type): ImmutableLongMapExtensions
186

187
implicit def toMutableLongMapExtensions(fact: mutable.LongMap.type): MutableLongMapExtensions
188
implicit def toMutableHashMapExtensions(fact: mutable.HashMap.type): MutableHashMapExtensions
189
implicit def toMutableListMapExtensions(fact: mutable.ListMap.type): MutableListMapExtensions
190
implicit def toMutableMapExtensions(fact: mutable.Map.type): MutableMapExtensions
191
```
192

193
## Usage Examples
194

195
### Iterator Extensions
196

197
```scala
198
import scala.collection.compat._
199

200
val iter1 = Iterator(1, 2, 3)
201
val iter2 = Iterator(4, 5, 6)
202
val list = List(1, 2, 3)
203

204
// Check if iterator has same elements as collection
205
val same = iter1.sameElements(list)  // true
206

207
// Concatenate iterator with collection
208
val combined = iter2.concat(list)  // Iterator(4, 5, 6, 1, 2, 3)
209
```
210

211
### Stream Extensions
212

213
```scala
214
import scala.collection.compat._
215

216
val stream = Stream(1, 2, 3)
217
val additional = List(4, 5, 6)
218

219
// Lazy append - additional elements computed on demand
220
val extended = stream.lazyAppendedAll(additional)
221
```
222

223
### Map Extensions
224

225
```scala
226
import scala.collection.compat._
227

228
val pairs = List(("a", 1), ("b", 2), ("c", 3))
229

230
// Immutable maps
231
val sortedMap = immutable.SortedMap.from(pairs)
232
val hashMap = immutable.HashMap.from(pairs)
233
val listMap = immutable.ListMap.from(pairs)
234

235
// Mutable maps
236
val mutableHash = mutable.HashMap.from(pairs)
237
val mutableList = mutable.ListMap.from(pairs)
238

239
// Specialized maps
240
val intMap = immutable.IntMap.from(List((1, "one"), (2, "two")))
241
val longMap = immutable.LongMap.from(List((1L, "one"), (2L, "two")))
242
```
243

244
### Sorted Collection Extensions
245

246
```scala
247
import scala.collection.compat._
248

249
val sortedSet = immutable.TreeSet(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
250

251
// Range operations
252
val fromFive = sortedSet.rangeFrom(5)    // TreeSet(5, 6, 7, 8, 9, 10)
253
val toSeven = sortedSet.rangeTo(7)       // TreeSet(1, 2, 3, 4, 5, 6, 7)
254
val untilEight = sortedSet.rangeUntil(8) // TreeSet(1, 2, 3, 4, 5, 6, 7)
255
```
256

257
### Generic Usage Pattern
258

259
```scala
260
import scala.collection.compat._
261

262
def processTraversable[A](data: TraversableOnce[A]): Vector[A] = {
263
  // Convert to iterator for uniform processing
264
  val iter = data.iterator
265
  
266
  // Process elements
267
  iter.filter(_ != null).to(Vector)
268
}
269

270
// Works with any TraversableOnce
271
val result1 = processTraversable(List(1, 2, null, 3))
272
val result2 = processTraversable(Set("a", "b", null, "c"))
273
```
274

275
These extensions provide a consistent API surface that works across Scala 2.11, 2.12, and 2.13, enabling forward-compatible code that uses 2.13 collection patterns.