0
# Primitive Collections
1

2
Eclipse Collections provides memory-efficient primitive collections for all 8 Java primitive types (`boolean`, `byte`, `char`, `double`, `float`, `int`, `long`, `short`), avoiding the performance overhead of autoboxing. Each primitive type has corresponding List, Set, Bag, Stack, and Map collections with both mutable and immutable variants.
3

4
## Primitive Base Interfaces
5

6
### PrimitiveIterable
7
Base interface for all primitive collection types.
8

9
```java { .api }
10
package org.eclipse.collections.api;
11

12
public interface PrimitiveIterable {
13
    int size();
14
    boolean isEmpty();
15
    boolean notEmpty();
16
    
17
    // String representation
18
    String makeString();
19
    String makeString(String separator);
20
    String makeString(String start, String separator, String end);
21
    void appendString(Appendable appendable);
22
    void appendString(Appendable appendable, String separator);
23
    void appendString(Appendable appendable, String start, String separator, String end);
24
}
25
```
26

27
### Primitive Type Iterables
28
Each primitive type has its own base iterable interface:
29

30
```java { .api }
31
// Boolean collections
32
package org.eclipse.collections.api;
33

34
public interface BooleanIterable extends PrimitiveIterable {
35
    BooleanIterator booleanIterator();
36
    
37
    // Primitive operations
38
    boolean[] toArray();
39
    boolean contains(boolean value);
40
    boolean containsAll(boolean... source);
41
    boolean containsAll(BooleanIterable source);
42
    
43
    // Functional operations
44
    void forEach(BooleanProcedure procedure);
45
    BooleanIterable select(BooleanPredicate predicate);
46
    BooleanIterable reject(BooleanPredicate predicate);
47
    <V> RichIterable<V> collect(BooleanToObjectFunction<? extends V> function);
48
    
49
    // Aggregation
50
    int count(BooleanPredicate predicate);
51
    boolean anySatisfy(BooleanPredicate predicate);
52
    boolean allSatisfy(BooleanPredicate predicate);
53
    boolean noneSatisfy(BooleanPredicate predicate);
54
    
55
    // Conversion
56
    MutableBooleanList toList();
57
    MutableBooleanSet toSet();
58
    MutableBooleanBag toBag();
59
}
60

61
// Integer collections (representative of all numeric primitive types)
62
package org.eclipse.collections.api.iterator;
63

64
public interface IntIterable extends PrimitiveIterable {
65
    IntIterator intIterator();
66
    
67
    // Primitive operations
68
    int[] toArray();
69
    boolean contains(int value);
70
    boolean containsAll(int... source);
71
    boolean containsAll(IntIterable source);
72
    
73
    // Functional operations
74
    void forEach(IntProcedure procedure);
75
    IntIterable select(IntPredicate predicate);
76
    IntIterable reject(IntPredicate predicate);
77
    <V> RichIterable<V> collect(IntToObjectFunction<? extends V> function);
78
    
79
    // Mathematical operations
80
    long sum();
81
    int max();
82
    int min();
83
    double average();
84
    double median();
85
    int[] toSortedArray();
86
    
87
    // Aggregation
88
    int count(IntPredicate predicate);
89
    boolean anySatisfy(IntPredicate predicate);
90
    boolean allSatisfy(IntPredicate predicate);
91
    boolean noneSatisfy(IntPredicate predicate);
92
    int detectIfNone(IntPredicate predicate, int ifNone);
93
    
94
    // Conversion
95
    MutableIntList toList();
96
    MutableIntSet toSet();
97
    MutableIntBag toBag();
98
    LazyIntIterable asLazy();
99
}
100
```
101

102
## Primitive Lists
103

104
### MutableIntList (Representative of all primitive lists)
105
Mutable primitive list avoiding boxing overhead for integers.
106

107
```java { .api }
108
package org.eclipse.collections.api.list.primitive;
109

110
public interface MutableIntList extends IntIterable {
111
    // List access operations
112
    int get(int index);
113
    int getFirst();
114
    int getLast();
115
    int indexOf(int value);
116
    int lastIndexOf(int value);
117
    
118
    // Modification operations
119
    void add(int element);
120
    boolean addAll(int... source);
121
    boolean addAll(IntIterable source);
122
    void addAtIndex(int index, int element);
123
    boolean addAllAtIndex(int index, int... source);
124
    boolean addAllAtIndex(int index, IntIterable source);
125
    
126
    boolean remove(int value);
127
    int removeAtIndex(int index);
128
    void clear();
129
    
130
    // List-specific operations
131
    int set(int index, int element);
132
    MutableIntList subList(int fromIndex, int toIndex);
133
    void sortThis();
134
    MutableIntList reverseThis();
135
    void shuffleThis();
136
    void shuffleThis(Random rnd);
137
    
138
    // Functional operations
139
    MutableIntList select(IntPredicate predicate);
140
    MutableIntList reject(IntPredicate predicate);
141
    <V> MutableList<V> collect(IntToObjectFunction<? extends V> function);
142
    
143
    // Primitive transformations
144
    MutableLongList collectLong(IntToLongFunction function);
145
    MutableDoubleList collectDouble(IntToDoubleFunction function);
146
    
147
    // With operations
148
    MutableIntList with(int element);
149
    MutableIntList without(int element);
150
    MutableIntList withAll(IntIterable elements);
151
    MutableIntList withoutAll(IntIterable elements);
152
    
153
    // Immutable copy
154
    ImmutableIntList toImmutable();
155
}
156
```
157

158
### ImmutableIntList (Representative of all primitive immutable lists)
159
Thread-safe immutable primitive list where all operations return new instances.
160

161
```java { .api }
162
package org.eclipse.collections.api.list.primitive;
163

164
public interface ImmutableIntList extends IntIterable {
165
    // List access operations
166
    int get(int index);
167
    int getFirst();
168
    int getLast();
169
    int indexOf(int value);
170
    int lastIndexOf(int value);
171
    
172
    // Sublist operations return new instances
173
    ImmutableIntList subList(int fromIndex, int toIndex);
174
    ImmutableIntList toReversed();
175
    
176
    // Modification operations return new instances
177
    ImmutableIntList newWith(int element);
178
    ImmutableIntList newWithout(int element);
179
    ImmutableIntList newWithAll(IntIterable elements);
180
    ImmutableIntList newWithoutAll(IntIterable elements);
181
    
182
    // Functional operations return new instances
183
    ImmutableIntList select(IntPredicate predicate);
184
    ImmutableIntList reject(IntPredicate predicate);
185
    <V> ImmutableList<V> collect(IntToObjectFunction<? extends V> function);
186
    
187
    // Primitive transformations return new instances
188
    ImmutableLongList collectLong(IntToLongFunction function);
189
    ImmutableDoubleList collectDouble(IntToDoubleFunction function);
190
}
191
```
192

193
## Primitive Sets
194

195
### MutableIntSet (Representative of all primitive sets)
196
Mutable primitive set with unique elements and set operations.
197

198
```java { .api }
199
package org.eclipse.collections.api.set.primitive;
200

201
public interface MutableIntSet extends IntIterable {
202
    // Set modification operations
203
    boolean add(int element);
204
    boolean addAll(int... source);
205
    boolean addAll(IntIterable source);
206
    boolean remove(int value);
207
    boolean removeAll(IntIterable source);
208
    boolean removeAll(int... source);
209
    boolean retainAll(IntIterable source);
210
    boolean retainAll(int... source);
211
    void clear();
212
    
213
    // Set operations
214
    MutableIntSet union(IntIterable set);
215
    MutableIntSet intersect(IntIterable set);
216
    MutableIntSet difference(IntIterable subtrahendSet);
217
    MutableIntSet symmetricDifference(IntIterable setB);
218
    
219
    // Functional operations
220
    MutableIntSet select(IntPredicate predicate);
221
    MutableIntSet reject(IntPredicate predicate);
222
    <V> MutableSet<V> collect(IntToObjectFunction<? extends V> function);
223
    
224
    // With operations
225
    MutableIntSet with(int element);
226
    MutableIntSet without(int element);
227
    MutableIntSet withAll(IntIterable elements);
228
    MutableIntSet withoutAll(IntIterable elements);
229
    
230
    // Immutable copy
231
    ImmutableIntSet toImmutable();
232
}
233
```
234

235
### ImmutableIntSet (Representative of all primitive immutable sets)
236
Thread-safe immutable primitive set where all operations return new instances.
237

238
```java { .api }
239
package org.eclipse.collections.api.set.primitive;
240

241
public interface ImmutableIntSet extends IntIterable {
242
    // Set operations return new instances
243
    ImmutableIntSet union(IntIterable set);
244
    ImmutableIntSet intersect(IntIterable set);
245
    ImmutableIntSet difference(IntIterable subtrahendSet);
246
    ImmutableIntSet symmetricDifference(IntIterable setB);
247
    
248
    // Modification operations return new instances
249
    ImmutableIntSet newWith(int element);
250
    ImmutableIntSet newWithout(int element);
251
    ImmutableIntSet newWithAll(IntIterable elements);
252
    ImmutableIntSet newWithoutAll(IntIterable elements);
253
    
254
    // Functional operations return new instances
255
    ImmutableIntSet select(IntPredicate predicate);
256
    ImmutableIntSet reject(IntPredicate predicate);
257
    <V> ImmutableSet<V> collect(IntToObjectFunction<? extends V> function);
258
}
259
```
260

261
## Primitive Bags
262

263
### MutableIntBag (Representative of all primitive bags)
264
Mutable primitive bag with occurrence counting for duplicates.
265

266
```java { .api }
267
package org.eclipse.collections.api.bag.primitive;
268

269
public interface MutableIntBag extends IntIterable {
270
    // Occurrence operations
271
    int occurrencesOf(int item);
272
    void forEachWithOccurrences(IntIntProcedure procedure);
273
    
274
    // Bag modification operations
275
    boolean add(int item);
276
    boolean remove(int item);
277
    boolean addOccurrences(int item, int occurrences);
278
    boolean removeOccurrences(int item, int occurrences);
279
    boolean setOccurrences(int item, int occurrences);
280
    
281
    // Bag operations
282
    int sizeDistinct();
283
    MutableIntBag selectByOccurrences(IntPredicate predicate);
284
    
285
    // Functional operations
286
    MutableIntBag select(IntPredicate predicate);
287
    MutableIntBag reject(IntPredicate predicate);
288
    <V> MutableBag<V> collect(IntToObjectFunction<? extends V> function);
289
    
290
    // With operations
291
    MutableIntBag with(int element);
292
    MutableIntBag without(int element);
293
    MutableIntBag withAll(IntIterable elements);
294
    MutableIntBag withoutAll(IntIterable elements);
295
    
296
    // Immutable copy
297
    ImmutableIntBag toImmutable();
298
}
299
```
300

301
### ImmutableIntBag (Representative of all primitive immutable bags)
302
Thread-safe immutable primitive bag where all operations return new instances.
303

304
```java { .api }
305
package org.eclipse.collections.api.bag.primitive;
306

307
public interface ImmutableIntBag extends IntIterable {
308
    // Occurrence operations
309
    int occurrencesOf(int item);
310
    void forEachWithOccurrences(IntIntProcedure procedure);
311
    
312
    // Bag operations
313
    int sizeDistinct();
314
    ImmutableIntBag selectByOccurrences(IntPredicate predicate);
315
    
316
    // Modification operations return new instances
317
    ImmutableIntBag newWith(int element);
318
    ImmutableIntBag newWithout(int element);
319
    ImmutableIntBag newWithAll(IntIterable elements);
320
    ImmutableIntBag newWithoutAll(IntIterable elements);
321
    ImmutableIntBag newWithOccurrences(int item, int occurrences);
322
    
323
    // Functional operations return new instances
324
    ImmutableIntBag select(IntPredicate predicate);
325
    ImmutableIntBag reject(IntPredicate predicate);
326
    <V> ImmutableBag<V> collect(IntToObjectFunction<? extends V> function);
327
}
328
```
329

330
## Primitive Stacks
331

332
### MutableIntStack (Representative of all primitive stacks)
333
Mutable primitive stack with LIFO operations.
334

335
```java { .api }
336
package org.eclipse.collections.api.stack.primitive;
337

338
public interface MutableIntStack extends IntIterable {
339
    // Stack operations
340
    void push(int item);
341
    int pop();
342
    int peek();
343
    int peekAt(int index);
344
    IntList peek(int count);
345
    IntList pop(int count);
346
    void clear();
347
    
348
    // Functional operations
349
    MutableIntStack select(IntPredicate predicate);
350
    MutableIntStack reject(IntPredicate predicate);
351
    <V> MutableStack<V> collect(IntToObjectFunction<? extends V> function);
352
    
353
    // With operations
354
    MutableIntStack with(int element);
355
    MutableIntStack without(int element);
356
    
357
    // Immutable copy
358
    ImmutableIntStack toImmutable();
359
}
360
```
361

362
### ImmutableIntStack (Representative of all primitive immutable stacks)
363
Thread-safe immutable primitive stack where all operations return new instances.
364

365
```java { .api }
366
package org.eclipse.collections.api.stack.primitive;
367

368
public interface ImmutableIntStack extends IntIterable {
369
    // Stack operations return new instances
370
    ImmutableIntStack push(int item);
371
    ImmutableIntStack pop();
372
    ImmutableIntStack pop(int count);
373
    
374
    // Stack access operations
375
    int peek();
376
    int peekAt(int index);
377
    IntList peek(int count);
378
    
379
    // Modification operations return new instances
380
    ImmutableIntStack newWith(int element);
381
    ImmutableIntStack newWithout(int element);
382
    
383
    // Functional operations return new instances
384
    ImmutableIntStack select(IntPredicate predicate);
385
    ImmutableIntStack reject(IntPredicate predicate);
386
    <V> ImmutableStack<V> collect(IntToObjectFunction<? extends V> function);
387
}
388
```
389

390
## Primitive Maps
391

392
Primitive maps provide efficient key-value storage avoiding boxing overhead. There are three variants for each primitive type combination:
393

394
### Object-to-Primitive Maps
395

396
```java { .api }
397
// ObjectIntMap - Object keys to int values
398
package org.eclipse.collections.api.map.primitive;
399

400
public interface ObjectIntMap<K> extends IntIterable {
401
    // Map operations
402
    int get(Object key);
403
    int getIfAbsent(Object key, int ifAbsent);
404
    int getOrThrow(Object key);
405
    
406
    boolean containsKey(Object key);
407
    boolean containsValue(int value);
408
    
409
    // Iteration
410
    void forEachKey(Procedure<? super K> procedure);
411
    void forEachValue(IntProcedure procedure);
412
    void forEachKeyValue(ObjectIntProcedure<? super K> procedure);
413
    
414
    // Views
415
    RichIterable<K> keysView();
416
    IntIterable values();
417
    
418
    // Conversion
419
    MutableObjectIntMap<K> toMap();
420
    ImmutableObjectIntMap<K> toImmutable();
421
}
422

423
public interface MutableObjectIntMap<K> extends ObjectIntMap<K> {
424
    // Modification operations
425
    void put(K key, int value);
426
    void putPair(ObjectIntPair<K> keyValuePair);
427
    void putAll(ObjectIntMap<? extends K> map);
428
    int updateValue(K key, int initialValueIfAbsent, IntToIntFunction function);
429
    
430
    // Removal operations
431
    void removeKey(K key);
432
    void remove(Object key);
433
    int removeKeyIfAbsent(K key, int value);
434
    void clear();
435
    
436
    // Functional operations
437
    MutableObjectIntMap<K> select(ObjectIntPredicate<? super K> predicate);
438
    MutableObjectIntMap<K> reject(ObjectIntPredicate<? super K> predicate);
439
    
440
    // With operations
441
    MutableObjectIntMap<K> withKeyValue(K key, int value);
442
    MutableObjectIntMap<K> withoutKey(K key);
443
    
444
    ImmutableObjectIntMap<K> toImmutable();
445
}
446

447
public interface ImmutableObjectIntMap<K> extends ObjectIntMap<K> {
448
    // Modification operations return new instances
449
    ImmutableObjectIntMap<K> newWithKeyValue(K key, int value);
450
    ImmutableObjectIntMap<K> newWithoutKey(K key);
451
    ImmutableObjectIntMap<K> newWithAllKeyValues(Iterable<ObjectIntPair<K>> keyValues);
452
    ImmutableObjectIntMap<K> newWithoutAllKeys(Iterable<? extends K> keys);
453
    
454
    // Functional operations return new instances
455
    ImmutableObjectIntMap<K> select(ObjectIntPredicate<? super K> predicate);
456
    ImmutableObjectIntMap<K> reject(ObjectIntPredicate<? super K> predicate);
457
}
458
```
459

460
### Primitive-to-Object Maps
461

462
```java { .api }
463
// IntObjectMap - int keys to Object values
464
package org.eclipse.collections.api.map.primitive;
465

466
public interface IntObjectMap<V> extends RichIterable<V> {
467
    // Map operations
468
    V get(int key);
469
    V getIfAbsent(int key, Function0<? extends V> ifAbsent);
470
    V getIfAbsentPut(int key, V value);
471
    V getIfAbsentPut(int key, Function0<? extends V> function);
472
    
473
    boolean containsKey(int key);
474
    boolean containsValue(Object value);
475
    
476
    // Iteration
477
    void forEachKey(IntProcedure procedure);
478
    void forEachValue(Procedure<? super V> procedure);
479
    void forEachKeyValue(IntObjectProcedure<? super V> procedure);
480
    
481
    // Views
482
    IntIterable keysView();
483
    RichIterable<V> valuesView();
484
    
485
    // Conversion
486
    MutableIntObjectMap<V> toMap();
487
    ImmutableIntObjectMap<V> toImmutable();
488
}
489

490
public interface MutableIntObjectMap<V> extends IntObjectMap<V> {
491
    // Modification operations
492
    V put(int key, V value);
493
    void putPair(IntObjectPair<V> keyValuePair);
494
    void putAll(IntObjectMap<? extends V> map);
495
    V updateValue(int key, Function0<? extends V> factory, Function<? super V, ? extends V> function);
496
    
497
    // Removal operations
498
    void removeKey(int key);
499
    void remove(int key);
500
    V removeKeyIfAbsent(int key, V value);
501
    void clear();
502
    
503
    // Functional operations
504
    <VV> MutableIntObjectMap<VV> collectValues(Function2<? super Integer, ? super V, ? extends VV> function);
505
    MutableIntObjectMap<V> select(IntObjectPredicate<? super V> predicate);
506
    MutableIntObjectMap<V> reject(IntObjectPredicate<? super V> predicate);
507
    
508
    // With operations
509
    MutableIntObjectMap<V> withKeyValue(int key, V value);
510
    MutableIntObjectMap<V> withoutKey(int key);
511
    
512
    ImmutableIntObjectMap<V> toImmutable();
513
}
514
```
515

516
### Primitive-to-Primitive Maps
517

518
```java { .api }
519
// IntIntMap - int keys to int values
520
package org.eclipse.collections.api.map.primitive;
521

522
public interface IntIntMap extends IntIterable {
523
    // Map operations
524
    int get(int key);
525
    int getIfAbsent(int key, int ifAbsent);
526
    int getOrThrow(int key);
527
    
528
    boolean containsKey(int key);
529
    boolean containsValue(int value);
530
    
531
    // Iteration
532
    void forEachKey(IntProcedure procedure);
533
    void forEachValue(IntProcedure procedure);
534
    void forEachKeyValue(IntIntProcedure procedure);
535
    
536
    // Views
537
    IntIterable keysView();
538
    IntIterable values();
539
    
540
    // Conversion
541
    MutableIntIntMap toMap();
542
    ImmutableIntIntMap toImmutable();
543
}
544

545
public interface MutableIntIntMap extends IntIntMap {
546
    // Modification operations
547
    void put(int key, int value);
548
    void putPair(IntIntPair keyValuePair);
549
    void putAll(IntIntMap map);
550
    int addToValue(int key, int toBeAdded);
551
    int updateValue(int key, int initialValueIfAbsent, IntToIntFunction function);
552
    
553
    // Removal operations
554
    void removeKey(int key);
555
    void remove(int key);
556
    int removeKeyIfAbsent(int key, int value);
557
    void clear();
558
    
559
    // Functional operations
560
    MutableIntIntMap select(IntIntPredicate predicate);
561
    MutableIntIntMap reject(IntIntPredicate predicate);
562
    
563
    // With operations
564
    MutableIntIntMap withKeyValue(int key, int value);
565
    MutableIntIntMap withoutKey(int key);
566
    
567
    ImmutableIntIntMap toImmutable();
568
}
569
```
570

571
## Complete Primitive Type Coverage
572

573
Eclipse Collections provides the above interfaces for all 8 primitive types:
574

575
### Boolean Collections
576
- `BooleanIterable`, `MutableBooleanList`, `ImmutableBooleanList`
577
- `MutableBooleanSet`, `ImmutableBooleanSet`
578
- `MutableBooleanBag`, `ImmutableBooleanBag`
579
- `MutableBooleanStack`, `ImmutableBooleanStack`
580
- Maps: `ObjectBooleanMap`, `BooleanObjectMap`, `BooleanBooleanMap`
581

582
### Byte Collections
583
- `ByteIterable`, `MutableByteList`, `ImmutableByteList`
584
- `MutableByteSet`, `ImmutableByteSet`
585
- `MutableByteBag`, `ImmutableByteBag`
586
- `MutableByteStack`, `ImmutableByteStack`
587
- Maps: `ObjectByteMap`, `ByteObjectMap`, `ByteByteMap`, plus cross-type maps like `ByteIntMap`
588

589
### Character Collections
590
- `CharIterable`, `MutableCharList`, `ImmutableCharList`
591
- `MutableCharSet`, `ImmutableCharSet`
592
- `MutableCharBag`, `ImmutableCharBag`
593
- `MutableCharStack`, `ImmutableCharStack`
594
- Maps: `ObjectCharMap`, `CharObjectMap`, `CharCharMap`, plus cross-type maps
595

596
### Numeric Collections (Double, Float, Int, Long, Short)
597
Each follows the same pattern as shown above with type-specific mathematical operations:
598
- `DoubleIterable`, `FloatIterable`, `IntIterable`, `LongIterable`, `ShortIterable`
599
- List, Set, Bag, Stack variants (Mutable and Immutable)
600
- Complete map coverage including cross-type primitive maps
601

602
## Usage Examples
603

604
### Working with Primitive Lists
605
```java { .api }
606
// Create primitive lists
607
MutableIntList numbers = IntLists.mutable.with(1, 2, 3, 4, 5);
608

609
// Mathematical operations (no boxing)
610
long sum = numbers.sum();           // 15
611
int max = numbers.max();            // 5
612
double average = numbers.average(); // 3.0
613

614
// Functional operations
615
MutableIntList evens = numbers.select(n -> n % 2 == 0);     // [2, 4]
616
MutableLongList squares = numbers.collectLong(n -> n * n); // [1, 4, 9, 16, 25]
617
```
618

619
### Working with Primitive Sets
620
```java { .api }
621
// Create primitive sets
622
MutableIntSet set1 = IntSets.mutable.with(1, 2, 3);
623
MutableIntSet set2 = IntSets.mutable.with(3, 4, 5);
624

625
// Set operations (no boxing)
626
MutableIntSet union = set1.union(set2);           // [1, 2, 3, 4, 5]
627
MutableIntSet intersection = set1.intersect(set2); // [3]
628
```
629

630
### Working with Primitive Maps
631
```java { .api }
632
// Create primitive maps
633
MutableObjectIntMap<String> counts = ObjectIntMaps.mutable.empty();
634
counts.put("apple", 5);
635
counts.put("banana", 3);
636

637
// Efficient operations (no boxing)
638
int appleCount = counts.get("apple");              // 5
639
counts.addToValue("apple", 2);                     // apple now has 7
640
int total = counts.sum();                          // 10
641

642
// Primitive-to-primitive maps
643
MutableIntIntMap squares = IntIntMaps.mutable.empty();
644
IntInterval.oneTo(100).forEach(i -> squares.put(i, i * i));
645
```
646

647
### Performance Benefits
648
```java { .api }
649
// Traditional collections (with boxing overhead)
650
List<Integer> boxedList = new ArrayList<>();
651
for (int i = 0; i < 1000000; i++) {
652
    boxedList.add(i); // Creates Integer objects
653
}
654

655
// Primitive collections (no boxing)
656
MutableIntList primitiveList = IntLists.mutable.empty();
657
for (int i = 0; i < 1000000; i++) {
658
    primitiveList.add(i); // Direct primitive storage
659
}
660
```
661

662
The primitive collections API provides significant memory and performance benefits by eliminating autoboxing overhead while maintaining the rich functional programming capabilities of Eclipse Collections.