0
# Collections
1

2
JavaScript-optimized implementations of Kotlin collection interfaces with specialized performance characteristics for JavaScript runtime. These collections provide mutable data structures with efficient operations adapted for JavaScript environments.
3

4
## Capabilities
5

6
### Mutable List Implementation
7

8
Resizable array implementation optimized for JavaScript runtime.
9

10
```kotlin { .api }
11
/**
12
 * Resizable array implementation of MutableList interface
13
 */
14
actual class ArrayList<E> : AbstractMutableList<E>, RandomAccess {
15
    constructor()
16
    constructor(initialCapacity: Int)
17
    constructor(elements: Collection<E>)
18
    
19
    actual override val size: Int
20
    actual override fun get(index: Int): E
21
    actual override fun set(index: Int, element: E): E
22
    actual override fun add(element: E): Boolean
23
    actual override fun add(index: Int, element: E)
24
    actual override fun remove(element: E): Boolean
25
    actual override fun removeAt(index: Int): E
26
    actual override fun clear()
27
    actual override fun indexOf(element: E): Int
28
    actual override fun lastIndexOf(element: E): Int
29
    actual override fun iterator(): MutableIterator<E>
30
    actual override fun listIterator(): MutableListIterator<E>
31
    actual override fun listIterator(index: Int): MutableListIterator<E>
32
    actual override fun subList(fromIndex: Int, toIndex: Int): MutableList<E>
33
}
34
```
35

36
**Usage Examples:**
37

38
```kotlin
39
// Create ArrayList
40
val list = ArrayList<String>()
41
val prefilledList = arrayListOf("apple", "banana", "cherry")
42

43
// Add elements
44
list.add("first")
45
list.add(0, "prepended") // Insert at specific position
46

47
// Access elements
48
val first = list[0]
49
val size = list.size
50

51
// Modify elements
52
list[1] = "modified"
53
list.removeAt(0)
54
list.remove("specific")
55

56
// Iteration
57
for (item in list) {
58
    println(item)
59
}
60

61
// Conversion
62
val regularList: List<String> = list
63
```
64

65
### Mutable Map Implementations
66

67
Hash table and linked hash map implementations for key-value storage.
68

69
```kotlin { .api }
70
/**
71
 * Hash table implementation of MutableMap interface
72
 */
73
actual class HashMap<K, V> : AbstractMutableMap<K, V> {
74
    constructor()
75
    constructor(initialCapacity: Int)
76
    constructor(original: Map<out K, V>)
77
    
78
    actual override val size: Int
79
    actual override val keys: MutableSet<K>
80
    actual override val values: MutableCollection<V>
81
    actual override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
82
    actual override fun get(key: K): V?
83
    actual override fun put(key: K, value: V): V?
84
    actual override fun remove(key: K): V?
85
    actual override fun clear()
86
    actual override fun containsKey(key: K): Boolean
87
    actual override fun containsValue(value: V): Boolean
88
}
89

90
/**
91
 * Insertion-ordered hash table implementation of MutableMap interface
92
 */
93
actual class LinkedHashMap<K, V> : HashMap<K, V> {
94
    constructor()
95
    constructor(initialCapacity: Int)
96
    constructor(original: Map<out K, V>)
97
    
98
    // Maintains insertion order for iteration
99
    actual override val keys: MutableSet<K>
100
    actual override val values: MutableCollection<V>
101
    actual override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
102
}
103
```
104

105
**Usage Examples:**
106

107
```kotlin
108
// Create HashMap
109
val map = HashMap<String, Int>()
110
val prefilledMap = hashMapOf("one" to 1, "two" to 2)
111

112
// Add entries
113
map["key"] = 42
114
map.put("another", 100)
115

116
// Access entries
117
val value = map["key"] // 42
118
val containsKey = map.containsKey("key") // true
119
val containsValue = map.containsValue(42) // true
120

121
// Iteration (unordered)
122
for ((key, value) in map) {
123
    println("$key -> $value")
124
}
125

126
// LinkedHashMap preserves insertion order
127
val linkedMap = LinkedHashMap<String, String>()
128
linkedMap["first"] = "A"
129
linkedMap["second"] = "B"
130
linkedMap["third"] = "C"
131

132
// Iteration maintains insertion order
133
for ((key, value) in linkedMap) {
134
    println("$key -> $value") // Always: first->A, second->B, third->C
135
}
136
```
137

138
### Mutable Set Implementations
139

140
Hash set and linked hash set implementations for unique element storage.
141

142
```kotlin { .api }
143
/**
144
 * Hash set implementation of MutableSet interface
145
 */
146
actual class HashSet<E> : AbstractMutableSet<E> {
147
    constructor()
148
    constructor(initialCapacity: Int)
149
    constructor(elements: Collection<E>)
150
    
151
    actual override val size: Int
152
    actual override fun add(element: E): Boolean
153
    actual override fun remove(element: E): Boolean
154
    actual override fun clear()
155
    actual override fun contains(element: E): Boolean
156
    actual override fun iterator(): MutableIterator<E>
157
}
158

159
/**
160
 * Insertion-ordered hash set implementation of MutableSet interface
161
 */
162
actual class LinkedHashSet<E> : HashSet<E> {
163
    constructor()
164
    constructor(initialCapacity: Int)
165
    constructor(elements: Collection<E>)
166
    
167
    // Maintains insertion order for iteration
168
    actual override fun iterator(): MutableIterator<E>
169
}
170
```
171

172
**Usage Examples:**
173

174
```kotlin
175
// Create HashSet
176
val set = HashSet<String>()
177
val prefilledSet = hashSetOf("red", "green", "blue")
178

179
// Add elements
180
set.add("unique")
181
set.add("unique") // Duplicate ignored
182

183
// Check membership
184
val contains = set.contains("unique") // true
185
val size = set.size
186

187
// Remove elements
188
set.remove("unique")
189
set.clear()
190

191
// LinkedHashSet preserves insertion order
192
val linkedSet = LinkedHashSet<Int>()
193
linkedSet.add(3)
194
linkedSet.add(1) 
195
linkedSet.add(2)
196

197
// Iteration maintains insertion order
198
for (item in linkedSet) {
199
    println(item) // Always: 3, 1, 2
200
}
201
```
202

203
### Abstract Base Classes
204

205
Base implementations providing common functionality for mutable collections.
206

207
```kotlin { .api }
208
/**
209
 * Abstract base class for mutable collections
210
 */
211
abstract class AbstractMutableCollection<E> : AbstractCollection<E>, MutableCollection<E> {
212
    abstract override fun add(element: E): Boolean
213
    abstract override fun remove(element: E): Boolean
214
    abstract override fun iterator(): MutableIterator<E>
215
    
216
    override fun clear() // Default implementation
217
    override fun addAll(elements: Collection<E>): Boolean // Default implementation
218
    override fun removeAll(elements: Collection<E>): Boolean // Default implementation
219
    override fun retainAll(elements: Collection<E>): Boolean // Default implementation
220
}
221

222
/**
223
 * Abstract base class for mutable lists
224
 */
225
abstract class AbstractMutableList<E> : AbstractMutableCollection<E>, MutableList<E> {
226
    abstract override fun get(index: Int): E
227
    abstract override fun set(index: Int, element: E): E
228
    abstract override fun add(index: Int, element: E)
229
    abstract override fun removeAt(index: Int): E
230
    
231
    override fun indexOf(element: E): Int // Default implementation
232
    override fun lastIndexOf(element: E): Int // Default implementation
233
    override fun listIterator(): MutableListIterator<E> // Default implementation
234
    override fun listIterator(index: Int): MutableListIterator<E> // Default implementation
235
    override fun subList(fromIndex: Int, toIndex: Int): MutableList<E> // Default implementation
236
}
237

238
/**
239
 * Abstract base class for mutable maps
240
 */
241
abstract class AbstractMutableMap<K, V> : AbstractMap<K, V>, MutableMap<K, V> {
242
    abstract override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
243
    
244
    override fun put(key: K, value: V): V? // Default implementation
245
    override fun remove(key: K): V? // Default implementation
246
    override fun clear() // Default implementation
247
    override fun putAll(from: Map<out K, V>) // Default implementation
248
    override val keys: MutableSet<K> // Default implementation
249
    override val values: MutableCollection<V> // Default implementation
250
}
251

252
/**
253
 * Abstract base class for mutable sets
254
 */
255
abstract class AbstractMutableSet<E> : AbstractMutableCollection<E>, MutableSet<E> {
256
    // Inherits from AbstractMutableCollection
257
    // No additional abstract methods required
258
}
259
```
260

261
### String-Optimized Collections
262

263
Specialized collection implementations optimized for String keys and elements.
264

265
```kotlin { .api }
266
/**
267
 * Create a string-optimized mutable map
268
 */
269
fun <V> stringMapOf(): MutableMap<String, V>
270
fun <V> stringMapOf(vararg pairs: Pair<String, V>): MutableMap<String, V>
271

272
/**
273
 * Create a string-optimized mutable set
274
 */
275
fun stringSetOf(): MutableSet<String>
276
fun stringSetOf(vararg elements: String): MutableSet<String>
277

278
/**
279
 * Create a linked string-optimized mutable map (preserves insertion order)
280
 */
281
fun <V> linkedStringMapOf(): MutableMap<String, V>
282
fun <V> linkedStringMapOf(vararg pairs: Pair<String, V>): MutableMap<String, V>
283

284
/**
285
 * Create a linked string-optimized mutable set (preserves insertion order)
286
 */
287
fun linkedStringSetOf(): MutableSet<String>
288
fun linkedStringSetOf(vararg elements: String): MutableSet<String>
289
```
290

291
**Usage Examples:**
292

293
```kotlin
294
// String-optimized collections (better performance for string operations)
295
val stringMap = stringMapOf(
296
    "name" to "John",
297
    "city" to "New York",
298
    "country" to "USA"
299
)
300

301
val stringSet = stringSetOf("apple", "banana", "cherry")
302

303
// Linked versions preserve insertion order
304
val linkedStringMap = linkedStringMapOf(
305
    "first" to "A",
306
    "second" to "B", 
307
    "third" to "C"
308
)
309

310
val linkedStringSet = linkedStringSetOf("red", "green", "blue")
311

312
// Use like regular collections
313
stringMap["age"] = "30"
314
stringSet.add("date")
315

316
// Iteration order is preserved for linked versions
317
for ((key, value) in linkedStringMap) {
318
    println("$key: $value") // Consistent order
319
}
320
```
321

322
### Collection Factory Functions
323

324
Convenient factory functions for creating pre-populated collections.
325

326
```kotlin { .api }
327
/**
328
 * Create ArrayList with initial elements
329
 */
330
fun <T> arrayListOf(): ArrayList<T>
331
fun <T> arrayListOf(vararg elements: T): ArrayList<T>
332

333
/**
334
 * Create HashMap with initial entries
335
 */  
336
fun <K, V> hashMapOf(): HashMap<K, V>
337
fun <K, V> hashMapOf(vararg pairs: Pair<K, V>): HashMap<K, V>
338

339
/**
340
 * Create HashSet with initial elements
341
 */
342
fun <T> hashSetOf(): HashSet<T>
343
fun <T> hashSetOf(vararg elements: T): HashSet<T>
344

345
/**
346
 * Create LinkedHashMap with initial entries (preserves insertion order)
347
 */
348
fun <K, V> linkedMapOf(): LinkedHashMap<K, V>
349
fun <K, V> linkedMapOf(vararg pairs: Pair<K, V>): LinkedHashMap<K, V>
350

351
/**
352
 * Create LinkedHashSet with initial elements (preserves insertion order)
353
 */
354
fun <T> linkedSetOf(): LinkedHashSet<T>
355
fun <T> linkedSetOf(vararg elements: T): LinkedHashSet<T>
356
```
357

358
**Usage Examples:**
359

360
```kotlin
361
// Empty collections
362
val list = arrayListOf<String>()
363
val map = hashMapOf<String, Int>()
364
val set = hashSetOf<Int>()
365

366
// Pre-populated collections
367
val fruits = arrayListOf("apple", "banana", "cherry")
368
val scores = hashMapOf("Alice" to 95, "Bob" to 87, "Carol" to 92)
369
val numbers = hashSetOf(1, 2, 3, 4, 5)
370

371
// Linked collections (preserve insertion order)
372
val orderedMap = linkedMapOf("first" to 1, "second" to 2, "third" to 3)
373
val orderedSet = linkedSetOf("red", "green", "blue")
374

375
// Type inference works
376
val auto = arrayListOf(1, 2, 3) // ArrayList<Int>
377
val autoMap = hashMapOf("key" to 42) // HashMap<String, Int>
378
```
379

380
## Types
381

382
```kotlin { .api }
383
// Concrete collection implementations
384
actual class ArrayList<E> : AbstractMutableList<E>, RandomAccess
385
actual class HashMap<K, V> : AbstractMutableMap<K, V>
386
actual class HashSet<E> : AbstractMutableSet<E>
387
actual class LinkedHashMap<K, V> : HashMap<K, V>
388
actual class LinkedHashSet<E> : HashSet<E>
389

390
// Abstract base classes
391
abstract class AbstractMutableCollection<E> : AbstractCollection<E>, MutableCollection<E>
392
abstract class AbstractMutableList<E> : AbstractMutableCollection<E>, MutableList<E>
393
abstract class AbstractMutableMap<K, V> : AbstractMap<K, V>, MutableMap<K, V>
394
abstract class AbstractMutableSet<E> : AbstractMutableCollection<E>, MutableSet<E>
395

396
// Marker interface for random access
397
interface RandomAccess
398

399
// Mutable collection interfaces (from kotlin.collections)
400
interface MutableCollection<E> : Collection<E>
401
interface MutableList<E> : List<E>, MutableCollection<E>
402
interface MutableSet<E> : Set<E>, MutableCollection<E>
403
interface MutableMap<K, V> : Map<K, V>
404

405
// Iterator interfaces
406
interface MutableIterator<T> : Iterator<T>
407
interface MutableListIterator<T> : ListIterator<T>, MutableIterator<T>
408
```