0
# Eclipse Collections
1

2
Eclipse Collections is a comprehensive Java collections library providing mutable and immutable collections, primitive collections, and various container types. It delivers productivity and performance through an expressive and efficient set of APIs and types with over 200 methods for functional programming operations.
3

4
## Package Information
5

6
- **Package Name**: eclipse-collections
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: org.eclipse.collections
10
- **Artifact ID**: eclipse-collections
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>org.eclipse.collections</groupId>
15
    <artifactId>eclipse-collections</artifactId>
16
    <version>13.0.0</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import org.eclipse.collections.api.list.MutableList;
24
import org.eclipse.collections.api.set.MutableSet;
25
import org.eclipse.collections.api.map.MutableMap;
26
import org.eclipse.collections.impl.factory.Lists;
27
import org.eclipse.collections.impl.factory.Sets;
28
import org.eclipse.collections.impl.factory.Maps;
29
```
30

31
For primitive collections (generated interfaces):
32

33
```java
34
import org.eclipse.collections.api.list.primitive.MutableIntList;
35
import org.eclipse.collections.api.set.primitive.MutableIntSet;
36
import org.eclipse.collections.impl.factory.primitive.IntLists;
37
import org.eclipse.collections.impl.factory.primitive.IntSets;
38
```
39

40
**Note**: Primitive collection interfaces and factory classes are generated at build time to provide specialized implementations for all Java primitive types (boolean, byte, char, short, int, long, float, double).
41

42
## Basic Usage
43

44
```java
45
import org.eclipse.collections.api.list.MutableList;
46
import org.eclipse.collections.impl.factory.Lists;
47

48
// Create collections using factory methods
49
MutableList<String> list = Lists.mutable.with("Alice", "Bob", "Charlie");
50
MutableSet<String> set = Sets.mutable.with("red", "green", "blue");
51
MutableMap<String, Integer> map = Maps.mutable.with("Alice", 25, "Bob", 30);
52

53
// Rich functional operations
54
MutableList<String> upperCaseNames = list
55
    .select(name -> name.length() > 3)
56
    .collect(String::toUpperCase);
57

58
// Primitive collections avoid boxing
59
MutableIntList numbers = IntLists.mutable.with(1, 2, 3, 4, 5);
60
int sum = numbers.sum();
61
MutableIntList doubled = numbers.collect(i -> i * 2);
62

63
// Immutable collections for safety
64
ImmutableList<String> immutableList = Lists.immutable.with("A", "B", "C");
65
ImmutableList<String> newList = immutableList.newWith("D");
66
```
67

68
## Architecture
69

70
Eclipse Collections is built around several key design principles:
71

72
- **Rich API**: Over 200+ methods on collection interfaces for functional programming operations
73
- **Mutable/Immutable Hierarchy**: Parallel hierarchies providing both mutable and immutable variants of all collection types
74
- **Primitive Collections**: Complete primitive collection support for all Java primitive types, avoiding boxing overhead
75
- **Factory Pattern**: Static factory classes (`Lists`, `Sets`, `Maps`, etc.) provide convenient entry points
76
- **RichIterable Foundation**: All collections extend `RichIterable<T>` providing consistent functional programming capabilities
77
- **Type Safety**: Strong typing throughout the API with generic type preservation in transformations
78
- **Memory Efficiency**: Optimized implementations with lower memory footprint than JDK collections
79
- **JDK Interoperability**: Seamless integration with standard Java collections through adapter methods
80

81
## Capabilities
82

83
### Factory Methods
84

85
Static factory classes providing convenient creation of all collection types with mutable, immutable, and fixed-size variants.
86

87
```java { .api }
88
// Main factory entry points
89
MutableList<T> Lists.mutable.empty();
90
MutableList<T> Lists.mutable.with(T... elements);
91
ImmutableList<T> Lists.immutable.of(T... elements);
92
FixedSizeList<T> Lists.fixedSize.with(T... elements);
93

94
MutableSet<T> Sets.mutable.with(T... elements);
95
ImmutableSet<T> Sets.immutable.of(T... elements);
96

97
MutableMap<K, V> Maps.mutable.empty();
98
MutableMap<K, V> Maps.mutable.with(K key, V value);
99
```
100

101
[Factory Methods](./factory-methods.md)
102

103
### Core Collection Interfaces
104

105
Comprehensive collection interfaces providing rich functionality for all collection types, built around the RichIterable foundation.
106

107
```java { .api }
108
interface RichIterable<T> extends InternalIterable<T> {
109
    // Filtering
110
    RichIterable<T> select(Predicate<? super T> predicate);
111
    RichIterable<T> reject(Predicate<? super T> predicate);
112
    
113
    // Transformation  
114
    <V> RichIterable<V> collect(Function<? super T, ? extends V> function);
115
    <V> RichIterable<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
116
    
117
    // Aggregation
118
    <IV> IV injectInto(IV injectedValue, Function2<? super IV, ? super T, ? extends IV> function);
119
    T detect(Predicate<? super T> predicate);
120
    
121
    // Testing
122
    boolean anySatisfy(Predicate<? super T> predicate);
123
    boolean allSatisfy(Predicate<? super T> predicate);
124
}
125
```
126

127
[Core Interfaces](./core-interfaces.md)
128

129
### Primitive Collections
130

131
Complete primitive collection APIs for all Java primitive types (boolean, byte, char, short, int, long, float, double) avoiding boxing overhead.
132

133
```java { .api }
134
interface IntIterable extends PrimitiveIterable {
135
    void forEach(IntProcedure procedure);
136
    IntIterable select(IntPredicate predicate);
137
    <V> RichIterable<V> collect(IntToObjectFunction<? extends V> function);
138
    long sum();
139
    int max();
140
    int min();
141
    double average();
142
}
143

144
interface MutableIntList extends IntIterable, MutableIntCollection {
145
    boolean add(int element);
146
    int get(int index);
147
    int set(int index, int element);
148
    MutableIntList with(int element);
149
}
150
```
151

152
[Primitive Collections](./primitive-collections.md)
153

154
### Functional Programming
155

156
Rich functional programming support with Functions, Predicates, Procedures and factory classes for common operations.
157

158
```java { .api }
159
// Core functional interfaces
160
interface Function<T, R> {
161
    R valueOf(T argument);
162
}
163

164
interface Predicate<T> {
165
    boolean accept(T object);
166
}
167

168
interface Procedure<T> {
169
    void value(T object);
170
}
171

172
// Factory classes for common patterns
173
class Predicates {
174
    static <T> Predicate<T> alwaysTrue();
175
    static <T> Predicate<T> equal(Object expected);
176
    static <T> Predicate<T> instanceOf(Class<?> clazz);
177
    static <T> Predicate<T> and(Predicate<? super T>... predicates);
178
}
179
```
180

181
[Functional Programming](./functional-programming.md)
182

183
### Advanced Features
184

185
Specialized collection types including Multimaps, BiMaps, Partitions, and utility APIs for advanced use cases.
186

187
```java { .api }
188
interface Multimap<K, V> {
189
    boolean put(K key, V value);
190
    RichIterable<V> get(K key);
191
    RichIterable<V> removeAll(Object key);
192
    Multimap<V, K> flip();
193
}
194

195
interface BiMap<K, V> extends MapIterable<K, V> {
196
    BiMap<V, K> inverse();
197
    V put(K key, V value);
198
}
199

200
interface PartitionIterable<T> {
201
    RichIterable<T> getSelected();
202
    RichIterable<T> getRejected();
203
}
204
```
205

206
[Advanced Features](./advanced-features.md)
207

208
## Types
209

210
### Core Type Hierarchy
211

212
```java { .api }
213
interface InternalIterable<T> {
214
    void forEach(Procedure<? super T> procedure);
215
    void forEachWith(Procedure2<? super T, ? super P> procedure, P parameter);
216
    void forEachWithIndex(ObjectIntProcedure<? super T> objectIntProcedure);
217
}
218

219
interface RichIterable<T> extends InternalIterable<T> {
220
    // Over 200 methods for functional operations
221
}
222

223
interface MutableCollection<T> extends Collection<T>, RichIterable<T> {
224
    boolean add(T item);
225
    boolean remove(Object item);
226
    MutableCollection<T> with(T element);
227
    MutableCollection<T> without(T element);
228
}
229

230
interface ImmutableCollection<T> extends RichIterable<T> {
231
    ImmutableCollection<T> newWith(T element);
232
    ImmutableCollection<T> newWithout(T element);
233
}
234
```
235

236
### Collection Type Interfaces
237

238
```java { .api }
239
// Lists
240
interface ListIterable<T> extends RichIterable<T>, OrderedIterable<T> {
241
    T get(int index);
242
    int indexOf(Object object);
243
    int lastIndexOf(Object object);
244
}
245

246
interface MutableList<T> extends MutableCollection<T>, List<T>, ListIterable<T> {
247
    void add(int index, T element);
248
    T set(int index, T element);
249
    T remove(int index);
250
    MutableList<T> sortThis();
251
    MutableList<T> reverseThis();
252
}
253

254
// Sets  
255
interface SetIterable<T> extends RichIterable<T> {
256
    SetIterable<T> union(SetIterable<? extends T> set);
257
    SetIterable<T> intersect(SetIterable<? extends T> set);
258
    SetIterable<T> difference(SetIterable<? extends T> subtrahend);
259
    boolean isSubsetOf(SetIterable<? extends T> candidateSuperset);
260
}
261

262
interface MutableSet<T> extends MutableCollection<T>, Set<T>, SetIterable<T> {
263
}
264

265
// Maps
266
interface MapIterable<K, V> extends RichIterable<V> {
267
    V get(Object key);
268
    boolean containsKey(Object key);
269
    V getIfAbsent(K key, Function0<? extends V> function);
270
    RichIterable<K> keysView();
271
    RichIterable<V> valuesView();
272
    RichIterable<Pair<K, V>> keyValuesView();
273
}
274

275
interface MutableMap<K, V> extends MutableMapIterable<K, V>, Map<K, V> {
276
    V put(K key, V value);
277
    V getIfAbsentPut(K key, Function0<? extends V> function);
278
    V updateValue(K key, Function0<? extends V> factory, Function<? super V, ? extends V> function);
279
    MutableMap<K, V> withKeyValue(K key, V value);
280
}
281
```