0
# Primitive Collections
1

2
Eclipse Collections provides complete primitive collection APIs for all Java primitive types (boolean, byte, char, short, int, long, float, double). These collections avoid boxing overhead and provide memory-efficient alternatives to object collections.
3

4
## Capabilities
5

6
### Overview
7

8
Primitive collections are organized in packages under `org.eclipse.collections.api` and `org.eclipse.collections.impl`:
9

10
- `org.eclipse.collections.api.collection.primitive` - Base primitive collection interfaces
11
- `org.eclipse.collections.api.list.primitive` - Primitive list interfaces  
12
- `org.eclipse.collections.api.set.primitive` - Primitive set interfaces
13
- `org.eclipse.collections.api.bag.primitive` - Primitive bag interfaces
14
- `org.eclipse.collections.api.stack.primitive` - Primitive stack interfaces
15
- `org.eclipse.collections.api.map.primitive` - Primitive map interfaces
16
- `org.eclipse.collections.impl.factory.primitive` - Factory classes
17

18
### Base Primitive Interfaces
19

20
Foundation interfaces for all primitive collections.
21

22
```java { .api }
23
/**
24
 * Root primitive iterable interface
25
 */
26
interface PrimitiveIterable {
27
    /**
28
     * Returns the number of elements
29
     * @return size of collection
30
     */
31
    int size();
32
    
33
    /**
34
     * Tests if collection is empty
35
     * @return true if empty
36
     */
37
    boolean isEmpty();
38
    
39
    /**
40
     * Tests if collection is not empty  
41
     * @return true if not empty
42
     */
43
    boolean notEmpty();
44
    
45
    /**
46
     * Convert to array of primitive wrapper objects
47
     * @return Object array containing wrapper objects
48
     */
49
    Object[] toArray();
50
    
51
    /**
52
     * Create string representation
53
     * @return string representation
54
     */
55
    String toString();
56
}
57

58
/**
59
 * Base mutable primitive collection interface
60
 */
61
interface MutablePrimitiveCollection<T> extends PrimitiveIterable {
62
    /**
63
     * Remove all elements
64
     */
65
    void clear();
66
    
67
    /**
68
     * Add all elements from source
69
     * @param source source iterable to add from
70
     * @return true if collection was modified
71
     */
72
    boolean addAll(PrimitiveIterable source);
73
    
74
    /**
75
     * Remove all elements from source
76
     * @param source source iterable to remove from
77
     * @return true if collection was modified
78
     */
79
    boolean removeAll(PrimitiveIterable source);
80
    
81
    /**
82
     * Retain only elements in source
83
     * @param source source iterable to retain
84
     * @return true if collection was modified
85
     */
86
    boolean retainAll(PrimitiveIterable source);
87
}
88

89
/**
90
 * Base immutable primitive collection interface
91
 */
92
interface ImmutablePrimitiveCollection<T> extends PrimitiveIterable {
93
    /**
94
     * Create new collection with element added
95
     * @param element element to add
96
     * @return new immutable collection
97
     */
98
    ImmutablePrimitiveCollection<T> newWith(T element);
99
    
100
    /**
101
     * Create new collection with element removed
102
     * @param element element to remove
103
     * @return new immutable collection
104
     */
105
    ImmutablePrimitiveCollection<T> newWithout(T element);
106
    
107
    /**
108
     * Create new collection with all elements added
109
     * @param elements elements to add
110
     * @return new immutable collection
111
     */
112
    ImmutablePrimitiveCollection<T> newWithAll(PrimitiveIterable elements);
113
    
114
    /**
115
     * Create new collection with all elements removed
116
     * @param elements elements to remove
117
     * @return new immutable collection
118
     */
119
    ImmutablePrimitiveCollection<T> newWithoutAll(PrimitiveIterable elements);
120
}
121
```
122

123
### Int Collections (Example for all primitive types)
124

125
Complete int collection interfaces - similar patterns exist for all primitive types.
126

127
```java { .api }
128
/**
129
 * Base int iterable providing core int collection operations
130
 */
131
interface IntIterable extends PrimitiveIterable {
132
    /**
133
     * Returns primitive int iterator
134
     * @return IntIterator for efficient iteration
135
     */
136
    IntIterator intIterator();
137
    
138
    /**
139
     * Execute procedure for each int element
140
     * @param procedure procedure to execute
141
     */
142
    void forEach(IntProcedure procedure);
143
    
144
    /**
145
     * Execute procedure for each element with index
146
     * @param procedure procedure receiving int and index
147
     */
148
    void forEachWithIndex(IntIntProcedure procedure);
149
    
150
    // Counting and testing
151
    /**
152
     * Count elements matching predicate
153
     * @param predicate predicate to test
154
     * @return count of matching elements
155
     */
156
    int count(IntPredicate predicate);
157
    
158
    /**
159
     * Test if any element matches predicate
160
     * @param predicate predicate to test
161
     * @return true if any match
162
     */
163
    boolean anySatisfy(IntPredicate predicate);
164
    
165
    /**
166
     * Test if all elements match predicate
167
     * @param predicate predicate to test  
168
     * @return true if all match
169
     */
170
    boolean allSatisfy(IntPredicate predicate);
171
    
172
    /**
173
     * Test if no elements match predicate
174
     * @param predicate predicate to test
175
     * @return true if none match
176
     */
177
    boolean noneSatisfy(IntPredicate predicate);
178
    
179
    // Filtering operations
180
    /**
181
     * Filter elements matching predicate
182
     * @param predicate predicate for filtering
183
     * @return IntIterable with matching elements
184
     */
185
    IntIterable select(IntPredicate predicate);
186
    
187
    /**
188
     * Filter elements not matching predicate
189
     * @param predicate predicate for filtering
190
     * @return IntIterable with non-matching elements
191
     */
192
    IntIterable reject(IntPredicate predicate);
193
    
194
    // Transformation operations
195
    /**
196
     * Transform each int to an object
197
     * @param function transformation function
198
     * @return RichIterable of transformed objects
199
     */
200
    <V> RichIterable<V> collect(IntToObjectFunction<? extends V> function);
201
    
202
    // Finding operations
203
    /**
204
     * Find first element matching predicate
205
     * @param predicate predicate for finding
206
     * @return first matching element
207
     * @throws NoSuchElementException if no match found
208
     */
209
    int detectIfNone(IntPredicate predicate, int ifNone);
210
    
211
    // Aggregation operations  
212
    /**
213
     * Sum all int values
214
     * @return sum as long to avoid overflow
215
     */
216
    long sum();
217
    
218
    /**
219
     * Find minimum int value
220
     * @return minimum value
221
     * @throws NoSuchElementException if empty
222
     */
223
    int min();
224
    
225
    /**
226
     * Find maximum int value  
227
     * @return maximum value
228
     * @throws NoSuchElementException if empty
229
     */
230
    int max();
231
    
232
    /**
233
     * Calculate average of all values
234
     * @return average as double
235
     */
236
    double average();
237
    
238
    /**
239
     * Calculate median of all values
240
     * @return median as double
241
     */
242
    double median();
243
    
244
    // Conversion operations
245
    /**
246
     * Convert to primitive int array
247
     * @return int array containing all elements
248
     */
249
    int[] toArray();
250
    
251
    /**
252
     * Convert to mutable int list
253
     * @return MutableIntList containing all elements
254
     */
255
    MutableIntList toList();
256
    
257
    /**
258
     * Convert to mutable int set
259
     * @return MutableIntSet containing all elements
260
     */
261
    MutableIntSet toSet();
262
    
263
    /**
264
     * Convert to mutable int bag
265
     * @return MutableIntBag containing all elements
266
     */
267
    MutableIntBag toBag();
268
    
269
    /**
270
     * Convert to sorted mutable int list
271
     * @return sorted MutableIntList
272
     */
273
    MutableIntList toSortedList();
274
    
275
    // String operations
276
    /**
277
     * Create string representation with separator
278
     * @param separator separator between elements
279
     * @return string representation
280
     */
281
    String makeString(String separator);
282
    
283
    /**
284
     * Create string representation with start, separator, and end
285
     * @param start starting delimiter
286
     * @param separator separator between elements  
287
     * @param end ending delimiter
288
     * @return string representation
289
     */
290
    String makeString(String start, String separator, String end);
291
    
292
    // Injection (reduce) operation
293
    /**
294
     * Reduce collection to single value using injected value and function
295
     * @param injectedValue starting value
296
     * @param function reduction function
297
     * @return reduced value
298
     */
299
    <T> T injectInto(T injectedValue, ObjectIntToObjectFunction<? super T, ? extends T> function);
300
}
301

302
/**
303
 * Mutable int collection interface
304
 */
305
interface MutableIntCollection extends IntIterable, MutablePrimitiveCollection<Integer> {
306
    // Modification operations
307
    /**
308
     * Add int element to collection
309
     * @param element element to add
310
     * @return true if collection was modified
311
     */
312
    boolean add(int element);
313
    
314
    /**
315
     * Add all int elements to collection
316
     * @param source array of elements to add
317
     * @return true if collection was modified
318
     */
319
    boolean addAll(int... source);
320
    
321
    /**
322
     * Add all elements from int iterable
323
     * @param source source iterable
324
     * @return true if collection was modified
325
     */
326
    boolean addAll(IntIterable source);
327
    
328
    /**
329
     * Remove int element from collection
330
     * @param value element to remove
331
     * @return true if element was removed
332
     */
333
    boolean remove(int value);
334
    
335
    /**
336
     * Remove all specified int elements
337
     * @param source array of elements to remove
338
     * @return true if collection was modified
339
     */
340
    boolean removeAll(int... source);
341
    
342
    /**
343
     * Remove all elements from int iterable
344
     * @param source source iterable to remove
345
     * @return true if collection was modified
346
     */
347
    boolean removeAll(IntIterable source);
348
    
349
    /**
350
     * Retain only specified elements
351
     * @param source array of elements to retain
352
     * @return true if collection was modified
353
     */
354
    boolean retainAll(int... source);
355
    
356
    /**
357
     * Retain only elements from int iterable
358
     * @param source source iterable to retain
359
     * @return true if collection was modified
360
     */
361
    boolean retainAll(IntIterable source);
362
    
363
    // Fluent API methods
364
    /**
365
     * Add element and return this collection for chaining
366
     * @param element element to add
367
     * @return this collection
368
     */
369
    MutableIntCollection with(int element);
370
    
371
    /**
372
     * Remove element and return this collection for chaining
373
     * @param element element to remove
374
     * @return this collection
375
     */
376
    MutableIntCollection without(int element);
377
    
378
    /**
379
     * Add all elements and return this collection for chaining
380
     * @param elements elements to add
381
     * @return this collection
382
     */
383
    MutableIntCollection withAll(IntIterable elements);
384
    
385
    /**
386
     * Remove all elements and return this collection for chaining
387
     * @param elements elements to remove
388
     * @return this collection
389
     */
390
    MutableIntCollection withoutAll(IntIterable elements);
391
    
392
    // Mutable transformations return new collections
393
    MutableIntCollection select(IntPredicate predicate);
394
    MutableIntCollection reject(IntPredicate predicate);
395
    <V> MutableCollection<V> collect(IntToObjectFunction<? extends V> function);
396
    
397
    // Parallel processing
398
    ParallelIntIterable asParallel(ExecutorService executorService, int batchSize);
399
    
400
    // Immutable view
401
    ImmutableIntCollection toImmutable();
402
}
403

404
/**
405
 * Immutable int collection interface
406
 */
407
interface ImmutableIntCollection extends IntIterable, ImmutablePrimitiveCollection<Integer> {
408
    // Immutable modification operations return new collections
409
    ImmutableIntCollection newWith(int element);
410
    ImmutableIntCollection newWithout(int element);  
411
    ImmutableIntCollection newWithAll(IntIterable elements);
412
    ImmutableIntCollection newWithoutAll(IntIterable elements);
413
    
414
    // Immutable transformations
415
    ImmutableIntCollection select(IntPredicate predicate);
416
    ImmutableIntCollection reject(IntPredicate predicate);
417
    <V> ImmutableCollection<V> collect(IntToObjectFunction<? extends V> function);
418
}
419
```
420

421
### Int List Interface
422

423
Indexed int collections providing list-specific operations.
424

425
```java { .api }
426
/**
427
 * Mutable int list providing indexed access
428
 */
429
interface MutableIntList extends MutableIntCollection {
430
    // Indexed access operations
431
    /**
432
     * Get int element at specified index
433
     * @param index index of element
434
     * @return element at index
435
     * @throws IndexOutOfBoundsException if index invalid
436
     */
437
    int get(int index);
438
    
439
    /**
440
     * Set int element at specified index
441
     * @param index index to set
442
     * @param element new element value
443
     * @return previous element at index
444
     * @throws IndexOutOfBoundsException if index invalid
445
     */
446
    int set(int index, int element);
447
    
448
    /**
449
     * Add int element at specified index
450
     * @param index index to add at
451
     * @param element element to add
452
     * @throws IndexOutOfBoundsException if index invalid
453
     */
454
    void addAtIndex(int index, int element);
455
    
456
    /**
457
     * Remove int element at specified index  
458
     * @param index index to remove
459
     * @return removed element
460
     * @throws IndexOutOfBoundsException if index invalid
461
     */
462
    int removeAtIndex(int index);
463
    
464
    // Search operations
465
    /**
466
     * Find first index of element
467
     * @param value element to find
468
     * @return index of element or -1 if not found
469
     */
470
    int indexOf(int value);
471
    
472
    /**
473
     * Find last index of element
474
     * @param value element to find  
475
     * @return last index of element or -1 if not found
476
     */
477
    int lastIndexOf(int value);
478
    
479
    // In-place operations
480
    /**
481
     * Sort this list in place
482
     * @return this list for chaining
483
     */
484
    MutableIntList sortThis();
485
    
486
    /**
487
     * Reverse this list in place
488
     * @return this list for chaining
489
     */
490
    MutableIntList reverseThis();
491
    
492
    /**
493
     * Shuffle this list in place
494
     * @return this list for chaining
495
     */
496
    MutableIntList shuffleThis();
497
    
498
    /**
499
     * Shuffle this list with specified random
500
     * @param rnd Random instance for shuffling
501
     * @return this list for chaining
502
     */
503
    MutableIntList shuffleThis(Random rnd);
504
    
505
    // List-specific transformations
506
    MutableIntList select(IntPredicate predicate);
507
    MutableIntList reject(IntPredicate predicate);
508
    <V> MutableList<V> collect(IntToObjectFunction<? extends V> function);
509
    
510
    // Fluent API
511
    MutableIntList with(int element);
512
    MutableIntList without(int element);
513
    MutableIntList withAll(IntIterable elements);
514
    MutableIntList withoutAll(IntIterable elements);
515
    
516
    // Sublist operations
517
    /**
518
     * Get sublist view
519
     * @param fromIndex starting index (inclusive)
520
     * @param toIndex ending index (exclusive)
521
     * @return MutableIntList view of sublist
522
     */
523
    MutableIntList subList(int fromIndex, int toIndex);
524
    
525
    // Immutable conversion
526
    ImmutableIntList toImmutable();
527
}
528

529
/**
530
 * Immutable int list interface
531
 */
532
interface ImmutableIntList extends ImmutableIntCollection {
533
    // Indexed access (read-only)
534
    int get(int index);
535
    int indexOf(int value);
536
    int lastIndexOf(int value);
537
    
538
    // Immutable modifications
539
    ImmutableIntList newWith(int element);
540
    ImmutableIntList newWithout(int element);
541
    ImmutableIntList newWithAll(IntIterable elements);
542
    ImmutableIntList newWithoutAll(IntIterable elements);
543
    
544
    // Immutable transformations
545
    ImmutableIntList select(IntPredicate predicate);
546
    ImmutableIntList reject(IntPredicate predicate);
547
    <V> ImmutableList<V> collect(IntToObjectFunction<? extends V> function);
548
    
549
    // Sublist
550
    ImmutableIntList subList(int fromIndex, int toIndex);
551
}
552
```
553

554
### Int Set Interface
555

556
Unique int collections providing set operations.
557

558
```java { .api }
559
/**
560
 * Mutable int set providing unique int elements
561
 */
562
interface MutableIntSet extends MutableIntCollection {
563
    // Set-specific operations
564
    /**
565
     * Test if element is contained in set
566
     * @param value element to test
567
     * @return true if contained
568
     */
569
    boolean contains(int value);
570
    
571
    /**
572
     * Test if all elements are contained in set
573
     * @param source elements to test
574
     * @return true if all contained
575
     */
576
    boolean containsAll(int... source);
577
    
578
    /**
579
     * Test if all elements from iterable are contained
580
     * @param source elements to test
581
     * @return true if all contained
582
     */
583
    boolean containsAll(IntIterable source);
584
    
585
    // Set algebra operations (return new sets)
586
    /**
587
     * Compute union with another int set
588
     * @param set other set
589
     * @return new MutableIntSet containing union
590
     */
591
    MutableIntSet union(IntSet set);
592
    
593
    /**
594
     * Compute intersection with another int set  
595
     * @param set other set
596
     * @return new MutableIntSet containing intersection
597
     */
598
    MutableIntSet intersect(IntSet set);
599
    
600
    /**
601
     * Compute difference with another int set
602
     * @param subtrahend set to subtract
603
     * @return new MutableIntSet containing difference  
604
     */
605
    MutableIntSet difference(IntSet subtrahend);
606
    
607
    /**
608
     * Compute symmetric difference with another int set
609
     * @param set other set
610
     * @return new MutableIntSet containing symmetric difference
611
     */
612
    MutableIntSet symmetricDifference(IntSet set);
613
    
614
    // Set transformations
615
    MutableIntSet select(IntPredicate predicate);
616
    MutableIntSet reject(IntPredicate predicate);
617
    <V> MutableSet<V> collect(IntToObjectFunction<? extends V> function);
618
    
619
    // Fluent API
620
    MutableIntSet with(int element);
621
    MutableIntSet without(int element);
622
    MutableIntSet withAll(IntIterable elements);
623
    MutableIntSet withoutAll(IntIterable elements);
624
    
625
    // Immutable conversion
626
    ImmutableIntSet toImmutable();
627
}
628

629
/**
630
 * Immutable int set interface
631
 */
632
interface ImmutableIntSet extends ImmutableIntCollection {
633
    // Set operations
634
    boolean contains(int value);
635
    boolean containsAll(int... source);
636
    boolean containsAll(IntIterable source);
637
    
638
    // Immutable set algebra
639
    ImmutableIntSet union(IntSet set);
640
    ImmutableIntSet intersect(IntSet set);
641
    ImmutableIntSet difference(IntSet subtrahend);
642
    ImmutableIntSet symmetricDifference(IntSet set);
643
    
644
    // Immutable modifications
645
    ImmutableIntSet newWith(int element);
646
    ImmutableIntSet newWithout(int element);
647
    ImmutableIntSet newWithAll(IntIterable elements);
648
    ImmutableIntSet newWithoutAll(IntIterable elements);
649
    
650
    // Immutable transformations
651
    ImmutableIntSet select(IntPredicate predicate);
652
    ImmutableIntSet reject(IntPredicate predicate);
653
    <V> ImmutableSet<V> collect(IntToObjectFunction<? extends V> function);
654
}
655
```
656

657
### Int Bag Interface
658

659
Multi-set int collections allowing duplicates with occurrence counting.
660

661
```java { .api }
662
/**
663
 * Mutable int bag (multiset) allowing duplicate elements with counts
664
 */
665
interface MutableIntBag extends MutableIntCollection {
666
    /**
667
     * Get occurrence count of element
668
     * @param item element to count
669
     * @return number of occurrences
670
     */
671
    int occurrencesOf(int item);
672
    
673
    /**
674
     * Get number of distinct elements
675
     * @return count of unique elements
676
     */
677
    int sizeDistinct();
678
    
679
    /**
680
     * Add multiple occurrences of element
681
     * @param item element to add
682
     * @param occurrences number of occurrences to add
683
     */
684
    void addOccurrences(int item, int occurrences);
685
    
686
    /**
687
     * Remove occurrences of element
688
     * @param item element to remove occurrences of
689
     * @param occurrences number of occurrences to remove
690
     * @return true if any were removed
691
     */
692
    boolean removeOccurrences(int item, int occurrences);
693
    
694
    /**
695
     * Set exact occurrence count of element
696
     * @param item element to set count for
697
     * @param occurrences target occurrence count
698
     */
699
    void setOccurrences(int item, int occurrences);
700
    
701
    /**
702
     * Convert to map of items to their occurrence counts
703
     * @return MutableObjectIntMap with item->count mappings
704
     */
705
    MutableObjectIntMap<Integer> toMapOfItemToCount();
706
    
707
    // Bag transformations
708
    MutableIntBag select(IntPredicate predicate);
709
    MutableIntBag reject(IntPredicate predicate);
710
    <V> MutableBag<V> collect(IntToObjectFunction<? extends V> function);
711
    
712
    // Fluent API
713
    MutableIntBag with(int element);
714
    MutableIntBag without(int element);
715
    MutableIntBag withAll(IntIterable elements);
716
    MutableIntBag withoutAll(IntIterable elements);
717
    
718
    // Immutable conversion
719
    ImmutableIntBag toImmutable();
720
}
721

722
/**
723
 * Immutable int bag interface
724
 */
725
interface ImmutableIntBag extends ImmutableIntCollection {
726
    // Bag-specific operations (read-only)
727
    int occurrencesOf(int item);
728
    int sizeDistinct();
729
    MutableObjectIntMap<Integer> toMapOfItemToCount();
730
    
731
    // Immutable modifications
732
    ImmutableIntBag newWith(int element);
733
    ImmutableIntBag newWithout(int element);
734
    ImmutableIntBag newWithAll(IntIterable elements);
735
    ImmutableIntBag newWithoutAll(IntIterable elements);
736
    
737
    // Immutable transformations
738
    ImmutableIntBag select(IntPredicate predicate);
739
    ImmutableIntBag reject(IntPredicate predicate);
740
    <V> ImmutableBag<V> collect(IntToObjectFunction<? extends V> function);
741
}
742
```
743

744
### Int Stack Interface
745

746
LIFO (Last In, First Out) int collections.
747

748
```java { .api }
749
/**
750
 * Mutable int stack providing LIFO access
751
 */
752
interface MutableIntStack extends MutableIntCollection {
753
    /**
754
     * Push element onto top of stack
755
     * @param item element to push
756
     */
757
    void push(int item);
758
    
759
    /**
760
     * Pop element from top of stack
761
     * @return top element
762
     * @throws EmptyStackException if empty
763
     */
764
    int pop();
765
    
766
    /**
767
     * Pop multiple elements from stack
768
     * @param count number of elements to pop
769
     * @return MutableIntList containing popped elements in order
770
     */
771
    MutableIntList pop(int count);
772
    
773
    /**
774
     * Peek at top element without removing
775
     * @return top element
776
     * @throws EmptyStackException if empty
777
     */
778
    int peek();
779
    
780
    /**
781
     * Peek at multiple top elements without removing
782
     * @param count number of elements to peek
783
     * @return MutableIntList containing top elements
784
     */
785
    MutableIntList peek(int count);
786
    
787
    /**
788
     * Peek at element at specified distance from top
789
     * @param index distance from top (0 = top element)
790
     * @return element at specified distance
791
     */
792
    int peekAt(int index);
793
    
794
    // Stack transformations
795
    MutableIntStack select(IntPredicate predicate);
796
    MutableIntStack reject(IntPredicate predicate);
797
    <V> MutableStack<V> collect(IntToObjectFunction<? extends V> function);
798
    
799
    // Immutable conversion
800
    ImmutableIntStack toImmutable();
801
}
802

803
/**
804
 * Immutable int stack interface
805
 */
806
interface ImmutableIntStack extends ImmutableIntCollection {
807
    // Stack operations (read-only)
808
    int peek();
809
    MutableIntList peek(int count);
810
    int peekAt(int index);
811
    
812
    // Immutable stack operations (return new stacks)
813
    ImmutableIntStack push(int item);
814
    ImmutableIntStack pop();
815
    ImmutableIntStack pop(int count);
816
    
817
    // Immutable modifications
818
    ImmutableIntStack newWith(int element);
819
    ImmutableIntStack newWithout(int element);
820
    ImmutableIntStack newWithAll(IntIterable elements);
821
    ImmutableIntStack newWithoutAll(IntIterable elements);
822
    
823
    // Immutable transformations
824
    ImmutableIntStack select(IntPredicate predicate);
825
    ImmutableIntStack reject(IntPredicate predicate);
826
    <V> ImmutableStack<V> collect(IntToObjectFunction<? extends V> function);
827
}
828
```
829

830
### Primitive Map Interfaces
831

832
Maps involving primitive keys and/or values.
833

834
```java { .api }
835
/**
836
 * Map from Object keys to int values
837
 */
838
interface ObjectIntMap<K> extends IntIterable {
839
    // Map operations
840
    /**
841
     * Get int value for key
842
     * @param key key to lookup
843
     * @return int value for key
844
     */
845
    int get(Object key);
846
    
847
    /**
848
     * Get int value for key or return default if not found
849
     * @param key key to lookup
850
     * @param ifAbsent default value if key not found
851
     * @return int value for key or default
852
     */
853
    int getIfAbsent(Object key, int ifAbsent);
854
    
855
    /**
856
     * Test if map contains key
857
     * @param key key to test
858
     * @return true if key is contained
859
     */
860
    boolean containsKey(Object key);
861
    
862
    /**
863
     * Test if map contains value
864
     * @param value value to test
865
     * @return true if value is contained
866
     */
867
    boolean containsValue(int value);
868
    
869
    // Views
870
    /**
871
     * Get view of all keys
872
     * @return RichIterable of keys
873
     */
874
    RichIterable<K> keysView();
875
    
876
    /**
877
     * Get view of all values as IntIterable
878
     * @return IntIterable of values
879
     */
880
    IntIterable valuesView();
881
    
882
    /**
883
     * Get view of key-value pairs
884
     * @return RichIterable of ObjectIntPair entries
885
     */
886
    RichIterable<ObjectIntPair<K>> keyValuesView();
887
    
888
    // Conversion
889
    /**
890
     * Convert to regular map with Integer values
891
     * @return MutableMap with Integer values
892
     */
893
    MutableMap<K, Integer> toMap();
894
}
895

896
/**
897
 * Mutable Object-to-int map
898
 */
899
interface MutableObjectIntMap<K> extends ObjectIntMap<K> {
900
    // Modification operations
901
    /**
902
     * Put key-value pair
903
     * @param key key to put
904
     * @param value int value to associate
905
     * @return previous value or 0 if no previous mapping
906
     */
907
    int put(K key, int value);
908
    
909
    /**
910
     * Put key-value pair only if key is not present
911
     * @param key key to put
912
     * @param value int value to associate
913
     * @return previous value or 0 if no previous mapping
914
     */
915
    int putIfAbsent(K key, int value);
916
    
917
    /**
918
     * Get value for key, putting and returning default if absent
919
     * @param key key to get/put
920
     * @param value default value to put if absent
921
     * @return existing value or the default value that was put
922
     */
923
    int getIfAbsentPut(K key, int value);
924
    
925
    /**
926
     * Get value for key, computing and putting if absent
927
     * @param key key to get/put
928
     * @param function function to compute value if absent
929
     * @return existing value or computed value that was put
930
     */
931
    int getIfAbsentPut(K key, IntFunction0 function);
932
    
933
    /**
934
     * Update value for key using factory and update function
935
     * @param key key to update
936
     * @param factory function to create initial value if key absent
937
     * @param function function to update existing value
938
     * @return updated value
939
     */
940
    int updateValue(K key, IntFunction0 factory, IntToIntFunction function);
941
    
942
    /**
943
     * Remove mapping for key
944
     * @param key key to remove
945
     * @return previous value or 0 if no mapping existed
946
     */
947
    int removeKey(Object key);
948
    
949
    /**
950
     * Remove mapping for key only if it maps to specified value
951
     * @param key key to remove
952
     * @param value value that must be mapped to key
953
     * @return true if mapping was removed
954
     */
955
    boolean remove(Object key, int value);
956
    
957
    // Bulk operations
958
    /**
959
     * Add value to existing mapping, putting initial value if key absent
960
     * @param key key to add to
961
     * @param toBeAdded value to add
962
     * @param initialValueIfAbsent initial value if key not present
963
     * @return updated value after addition
964
     */
965
    int addToValue(K key, int toBeAdded, int initialValueIfAbsent);
966
    
967
    /**
968
     * Put all mappings from another ObjectIntMap
969
     * @param map map to copy from
970
     */
971
    void putAll(ObjectIntMap<? extends K> map);
972
    
973
    // Fluent API
974
    MutableObjectIntMap<K> withKeyValue(K key, int value);
975
    MutableObjectIntMap<K> withoutKey(K key);
976
    MutableObjectIntMap<K> withoutAllKeys(Iterable<? extends K> keys);
977
    
978
    // Transformations
979
    MutableObjectIntMap<K> select(ObjectIntPredicate<? super K> predicate);
980
    MutableObjectIntMap<K> reject(ObjectIntPredicate<? super K> predicate);
981
    
982
    // Immutable conversion
983
    ImmutableObjectIntMap<K> toImmutable();
984
}
985

986
/**
987
 * Map from int keys to Object values  
988
 */
989
interface IntObjectMap<V> extends RichIterable<V> {
990
    // Map operations
991
    V get(int key);
992
    V getIfAbsent(int key, V ifAbsent);
993
    boolean containsKey(int key);
994
    boolean containsValue(Object value);
995
    
996
    // Views
997
    IntIterable keysView();
998
    RichIterable<V> valuesView();  
999
    RichIterable<IntObjectPair<V>> keyValuesView();
1000
    
1001
    // Size operations
1002
    int size();
1003
    boolean isEmpty();
1004
}
1005

1006
/**
1007
 * Mutable int-to-Object map
1008
 */
1009
interface MutableIntObjectMap<V> extends IntObjectMap<V> {
1010
    // Modification operations
1011
    V put(int key, V value);
1012
    V putIfAbsent(int key, V value);
1013
    V getIfAbsentPut(int key, V value);
1014
    V getIfAbsentPut(int key, Function0<? extends V> function);
1015
    <P> V getIfAbsentPutWith(int key, Function<? super P, ? extends V> function, P parameter);
1016
    V updateValue(int key, Function0<? extends V> factory, Function<? super V, ? extends V> function);
1017
    <P> V updateValueWith(int key, Function0<? extends V> factory, Function2<? super V, ? super P, ? extends V> function, P parameter);
1018
    
1019
    V remove(int key);
1020
    boolean remove(int key, Object value);
1021
    
1022
    // Bulk operations  
1023
    void putAll(IntObjectMap<? extends V> map);
1024
    
1025
    // Fluent API
1026
    MutableIntObjectMap<V> withKeyValue(int key, V value);
1027
    MutableIntObjectMap<V> withoutKey(int key);
1028
    MutableIntObjectMap<V> withoutAllKeys(IntIterable keys);
1029
    
1030
    // Transformations
1031
    MutableIntObjectMap<V> select(IntObjectPredicate<? super V> predicate);
1032
    MutableIntObjectMap<V> reject(IntObjectPredicate<? super V> predicate);
1033
    <V2> MutableIntObjectMap<V2> collectValues(Function<? super V, ? extends V2> function);
1034
    
1035
    // Immutable conversion
1036
    ImmutableIntObjectMap<V> toImmutable();
1037
}
1038

1039
/**
1040
 * Map from int keys to int values
1041
 */
1042
interface IntIntMap extends IntIterable {
1043
    // Map operations
1044
    int get(int key);
1045
    int getIfAbsent(int key, int ifAbsent);
1046
    boolean containsKey(int key);
1047
    boolean containsValue(int value);
1048
    
1049
    // Views
1050
    IntIterable keysView();
1051
    IntIterable valuesView();
1052
    RichIterable<IntIntPair> keyValuesView();
1053
    
1054
    // Size operations  
1055
    int size();
1056
    boolean isEmpty();
1057
}
1058

1059
/**
1060
 * Mutable int-to-int map
1061
 */
1062
interface MutableIntIntMap extends IntIntMap {
1063
    // Modification operations
1064
    int put(int key, int value);
1065
    int putIfAbsent(int key, int value);
1066
    int getIfAbsentPut(int key, int value);
1067
    int getIfAbsentPut(int key, IntFunction0 function);
1068
    int updateValue(int key, IntFunction0 factory, IntToIntFunction function);
1069
    int addToValue(int key, int toBeAdded, int initialValueIfAbsent);
1070
    
1071
    int remove(int key);
1072
    boolean remove(int key, int value);
1073
    
1074
    // Bulk operations
1075
    void putAll(IntIntMap map);
1076
    
1077
    // Fluent API  
1078
    MutableIntIntMap withKeyValue(int key, int value);
1079
    MutableIntIntMap withoutKey(int key);
1080
    MutableIntIntMap withoutAllKeys(IntIterable keys);
1081
    
1082
    // Transformations
1083
    MutableIntIntMap select(IntIntPredicate predicate);
1084
    MutableIntIntMap reject(IntIntPredicate predicate);
1085
    
1086
    // Immutable conversion
1087
    ImmutableIntIntMap toImmutable();
1088
}
1089
```
1090

1091
### Primitive Factory Classes
1092

1093
Factory classes for creating primitive collections.
1094

1095
```java { .api }
1096
/**
1097
 * Factory for creating int lists
1098
 */
1099
public final class IntLists {
1100
    public static final ImmutableIntListFactory immutable;
1101
    public static final MutableIntListFactory mutable;
1102
}
1103

1104
interface MutableIntListFactory {
1105
    MutableIntList empty();
1106
    MutableIntList with(int... elements);
1107
    MutableIntList withAll(IntIterable items);
1108
    MutableIntList withInitialCapacity(int initialCapacity);
1109
}
1110

1111
interface ImmutableIntListFactory {
1112
    ImmutableIntList empty();
1113
    ImmutableIntList of(int... elements);
1114
    ImmutableIntList ofAll(IntIterable items);
1115
}
1116

1117
/**
1118
 * Factory for creating int sets
1119
 */
1120
public final class IntSets {
1121
    public static final ImmutableIntSetFactory immutable;
1122
    public static final MutableIntSetFactory mutable;
1123
}
1124

1125
/**
1126
 * Factory for creating int bags
1127
 */
1128
public final class IntBags {
1129
    public static final ImmutableIntBagFactory immutable;
1130
    public static final MutableIntBagFactory mutable;
1131
}
1132

1133
/**
1134
 * Factory for creating int stacks
1135
 */
1136
public final class IntStacks {
1137
    public static final ImmutableIntStackFactory immutable;
1138
    public static final MutableIntStackFactory mutable;
1139
}
1140

1141
/**
1142
 * Factory for creating Object-to-int maps
1143
 */
1144
public final class ObjectIntMaps {
1145
    public static final ImmutableObjectIntMapFactory immutable;
1146
    public static final MutableObjectIntMapFactory mutable;
1147
}
1148

1149
/**
1150
 * Factory for creating int-to-Object maps
1151
 */
1152
public final class IntObjectMaps {
1153
    public static final ImmutableIntObjectMapFactory immutable;
1154
    public static final MutableIntObjectMapFactory mutable;
1155
}
1156

1157
/**
1158
 * Factory for creating int-to-int maps  
1159
 */
1160
public final class IntIntMaps {
1161
    public static final ImmutableIntIntMapFactory immutable;
1162
    public static final MutableIntIntMapFactory mutable;
1163
}
1164
```
1165

1166
### Primitive Tuples
1167

1168
Tuple types for primitive combinations.
1169

1170
```java { .api }
1171
/**
1172
 * Factory for creating primitive tuples
1173
 */
1174
public final class PrimitiveTuples {
1175
    // Object-Primitive pairs
1176
    public static <T> ObjectIntPair<T> pair(T one, int two);
1177
    public static <T> ObjectBooleanPair<T> pair(T one, boolean two);
1178
    public static <T> ObjectBytePair<T> pair(T one, byte two);
1179
    public static <T> ObjectCharPair<T> pair(T one, char two);
1180
    public static <T> ObjectDoublePair<T> pair(T one, double two);
1181
    public static <T> ObjectFloatPair<T> pair(T one, float two);
1182
    public static <T> ObjectLongPair<T> pair(T one, long two);
1183
    public static <T> ObjectShortPair<T> pair(T one, short two);
1184
    
1185
    // Primitive-Object pairs
1186
    public static <T> IntObjectPair<T> pair(int one, T two);
1187
    public static <T> BooleanObjectPair<T> pair(boolean one, T two);
1188
    public static <T> ByteObjectPair<T> pair(byte one, T two);
1189
    public static <T> CharObjectPair<T> pair(char one, T two);
1190
    public static <T> DoubleObjectPair<T> pair(double one, T two);
1191
    public static <T> FloatObjectPair<T> pair(float one, T two);
1192
    public static <T> LongObjectPair<T> pair(long one, T two);
1193
    public static <T> ShortObjectPair<T> pair(short one, T two);
1194
    
1195
    // Primitive-Primitive pairs
1196
    public static IntIntPair pair(int one, int two);
1197
    public static BooleanBooleanPair pair(boolean one, boolean two);
1198
    public static ByteBytePair pair(byte one, byte two);
1199
    public static CharCharPair pair(char one, char two);
1200
    public static DoubleDoublePair pair(double one, double two);
1201
    public static FloatFloatPair pair(float one, float two);
1202
    public static LongLongPair pair(long one, long two);
1203
    public static ShortShortPair pair(short one, short two);
1204
}
1205

1206
/**
1207
 * Pair containing Object and int
1208
 */
1209
interface ObjectIntPair<T> {
1210
    T getOne();
1211
    int getTwo();
1212
}
1213

1214
/**
1215
 * Pair containing int and Object  
1216
 */
1217
interface IntObjectPair<T> {
1218
    int getOne();
1219
    T getTwo();
1220
}
1221

1222
/**
1223
 * Pair containing two ints
1224
 */
1225
interface IntIntPair {
1226
    int getOne();
1227
    int getTwo();
1228
}
1229
```
1230

1231
## Usage Examples
1232

1233
**Creating Primitive Collections:**
1234

1235
```java
1236
import org.eclipse.collections.impl.factory.primitive.IntLists;
1237
import org.eclipse.collections.impl.factory.primitive.IntSets;
1238
import org.eclipse.collections.impl.factory.primitive.IntBags;
1239

1240
// Create primitive lists
1241
MutableIntList numbers = IntLists.mutable.with(1, 2, 3, 4, 5);
1242
ImmutableIntList immutableNumbers = IntLists.immutable.of(10, 20, 30);
1243

1244
// Create primitive sets
1245
MutableIntSet uniqueNumbers = IntSets.mutable.with(1, 2, 2, 3, 3, 3); // [1, 2, 3]
1246
ImmutableIntSet immutableSet = IntSets.immutable.of(100, 200, 300);
1247

1248
// Create primitive bags  
1249
MutableIntBag numberCounts = IntBags.mutable.with(1, 1, 2, 2, 2, 3);
1250
// 1 appears 2 times, 2 appears 3 times, 3 appears 1 time
1251
```
1252

1253
**Functional Operations:**
1254

1255
```java
1256
import org.eclipse.collections.api.block.predicate.primitive.IntPredicate;
1257
import org.eclipse.collections.api.block.function.primitive.IntToObjectFunction;
1258

1259
MutableIntList numbers = IntLists.mutable.with(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
1260

1261
// Filtering with predicates
1262
IntPredicate isEven = i -> i % 2 == 0;
1263
MutableIntList evenNumbers = numbers.select(isEven); // [2, 4, 6, 8, 10]
1264
MutableIntList oddNumbers = numbers.reject(isEven);  // [1, 3, 5, 7, 9]
1265

1266
// Transformation to objects  
1267
IntToObjectFunction<String> intToString = i -> "Number: " + i;
1268
MutableList<String> strings = numbers.collect(intToString);
1269

1270
// Aggregation operations
1271
long sum = numbers.sum();           // 55
1272
int max = numbers.max();            // 10
1273
int min = numbers.min();            // 1
1274
double average = numbers.average(); // 5.5
1275

1276
// Testing operations
1277
boolean hasEven = numbers.anySatisfy(isEven);  // true
1278
boolean allPositive = numbers.allSatisfy(i -> i > 0); // true
1279
int evenCount = numbers.count(isEven); // 5
1280
```
1281

1282
**Primitive Maps:**
1283

1284
```java
1285
import org.eclipse.collections.impl.factory.primitive.ObjectIntMaps;
1286
import org.eclipse.collections.impl.factory.primitive.IntObjectMaps;
1287

1288
// Object-to-int maps
1289
MutableObjectIntMap<String> wordCounts = ObjectIntMaps.mutable.empty();
1290
wordCounts.put("hello", 5);
1291
wordCounts.put("world", 3);
1292
wordCounts.addToValue("hello", 2, 0); // Add 2 to existing value: 5 + 2 = 7
1293

1294
int helloCount = wordCounts.get("hello"); // 7
1295
int unknownCount = wordCounts.getIfAbsent("unknown", 0); // 0
1296

1297
// Int-to-Object maps
1298
MutableIntObjectMap<String> idToName = IntObjectMaps.mutable.empty();
1299
idToName.put(1, "Alice");
1300
idToName.put(2, "Bob");
1301
idToName.put(3, "Charlie");
1302

1303
String name = idToName.get(2); // "Bob"
1304
String defaultName = idToName.getIfAbsent(999, "Unknown"); // "Unknown"
1305

1306
// Int-to-int maps
1307
MutableIntIntMap squares = IntIntMaps.mutable.empty();
1308
squares.put(1, 1);
1309
squares.put(2, 4);
1310
squares.put(3, 9);
1311
squares.put(4, 16);
1312

1313
int squareOfThree = squares.get(3); // 9
1314
```
1315

1316
## Performance Benefits
1317

1318
Primitive collections provide significant performance advantages:
1319

1320
1. **Memory Efficiency**: No boxing overhead - int uses 4 bytes vs Integer using ~16 bytes
1321
2. **CPU Performance**: Direct primitive operations without object allocation
1322
3. **Garbage Collection**: Reduced GC pressure from fewer object allocations  
1323
4. **Cache Locality**: Better CPU cache utilization with primitive arrays
1324

1325
**Performance Example:**
1326

1327
```java
1328
// Object collection - creates Integer objects
1329
MutableList<Integer> objectList = Lists.mutable.empty();
1330
for (int i = 0; i < 1_000_000; i++) {
1331
    objectList.add(i); // Boxing: int -> Integer
1332
}
1333
int sum1 = objectList.sumOfInt(Integer::intValue); // Unboxing required
1334

1335
// Primitive collection - no boxing
1336
MutableIntList primitiveList = IntLists.mutable.empty();
1337
for (int i = 0; i < 1_000_000; i++) {
1338
    primitiveList.add(i); // Direct primitive storage
1339
}
1340
long sum2 = primitiveList.sum(); // Direct primitive operation
1341
```
1342

1343
The primitive version uses ~4x less memory and runs significantly faster due to eliminating boxing/unboxing operations.