0
# Eclipse Collections API
1

2
Eclipse Collections is a comprehensive collections framework for Java that provides interfaces for object collections, primitive collections, and lazy iterables. This API module defines 238 interfaces for a rich set of collection types with extensive functional programming capabilities.
3

4
## Package Information
5

6
- **Package Name**: eclipse-collections-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10

11
Maven:
12
```xml
13
<dependency>
14
    <groupId>org.eclipse.collections</groupId>
15
    <artifactId>eclipse-collections-api</artifactId>
16
    <version>13.0.0</version>
17
</dependency>
18
```
19

20
Gradle:
21
```groovy
22
implementation 'org.eclipse.collections:eclipse-collections-api:13.0.0'
23
```
24

25
**Base Package:** `org.eclipse.collections.api`
26

27
## Core Imports
28

29
```java { .api }
30
// Core collection interfaces
31
import org.eclipse.collections.api.RichIterable;
32
import org.eclipse.collections.api.LazyIterable;
33
import org.eclipse.collections.api.ParallelIterable;
34

35
// List collections
36
import org.eclipse.collections.api.list.ListIterable;
37
import org.eclipse.collections.api.list.MutableList;
38
import org.eclipse.collections.api.list.ImmutableList;
39

40
// Set collections
41
import org.eclipse.collections.api.set.SetIterable;
42
import org.eclipse.collections.api.set.MutableSet;
43
import org.eclipse.collections.api.set.ImmutableSet;
44

45
// Map collections
46
import org.eclipse.collections.api.map.MapIterable;
47
import org.eclipse.collections.api.map.MutableMap;
48
import org.eclipse.collections.api.map.ImmutableMap;
49

50
// Factory classes
51
import org.eclipse.collections.api.factory.Lists;
52
import org.eclipse.collections.api.factory.Sets;
53
import org.eclipse.collections.api.factory.Maps;
54

55
// Functional interfaces
56
import org.eclipse.collections.api.block.function.Function;
57
import org.eclipse.collections.api.block.predicate.Predicate;
58
import org.eclipse.collections.api.block.procedure.Procedure;
59

60
// Ordering interfaces
61
import org.eclipse.collections.api.ordered.OrderedIterable;
62
import org.eclipse.collections.api.ordered.ReversibleIterable;
63
import org.eclipse.collections.api.ordered.SortedIterable;
64

65
// Tuple interfaces
66
import org.eclipse.collections.api.tuple.Pair;
67
import org.eclipse.collections.api.tuple.Triple;
68
import org.eclipse.collections.api.tuple.Twin;
69
import org.eclipse.collections.api.tuple.Triplet;
70

71
// Partition interface
72
import org.eclipse.collections.api.partition.PartitionIterable;
73
```
74

75
## Basic Usage
76

77
### Collection Creation
78
```java { .api }
79
// Create mutable collections
80
MutableList<String> list = Lists.mutable.with("a", "b", "c");
81
MutableSet<Integer> set = Sets.mutable.with(1, 2, 3);
82
MutableMap<String, Integer> map = Maps.mutable.with("key1", 1, "key2", 2);
83

84
// Create immutable collections
85
ImmutableList<String> immutableList = Lists.immutable.with("a", "b", "c");
86
ImmutableSet<Integer> immutableSet = Sets.immutable.with(1, 2, 3);
87
ImmutableMap<String, Integer> immutableMap = Maps.immutable.with("key1", 1, "key2", 2);
88
```
89

90
### Functional Operations
91
```java { .api }
92
// Using RichIterable functional methods
93
RichIterable<String> names = Lists.mutable.with("John", "Jane", "Bob");
94

95
// Filter elements
96
RichIterable<String> filtered = names.select(name -> name.startsWith("J"));
97

98
// Transform elements
99
RichIterable<Integer> lengths = names.collect(String::length);
100

101
// Find elements
102
String found = names.detect(name -> name.contains("o"));
103

104
// Partition elements
105
PartitionIterable<String> partition = names.partition(name -> name.length() > 3);
106
```
107

108
## Capabilities
109

110
### [Core Collections](core-collections.md)
111
Comprehensive collection interfaces including Lists, Sets, Bags, and Stacks with both mutable and immutable variants, including sorted collections.
112

113
```java { .api }
114
// List operations
115
ListIterable<T> extends RichIterable<T>
116
MutableList<T> extends MutableCollection<T>, List<T>, ListIterable<T>
117
ImmutableList<T> extends ListIterable<T>
118

119
// Set operations with mathematical functions
120
SetIterable<T> extends RichIterable<T>
121
MutableSet<T> extends MutableCollection<T>, Set<T>, SetIterable<T>
122
ImmutableSet<T> extends SetIterable<T>
123

124
// Sorted set operations
125
SortedSetIterable<T> extends SetIterable<T>, SortedIterable<T>
126
MutableSortedSet<T> extends MutableSet<T>, SortedSet<T>, SortedSetIterable<T>
127
ImmutableSortedSet<T> extends SortedSetIterable<T>
128

129
// Bag operations (multiset with occurrence counting)
130
Bag<T> extends RichIterable<T>
131
MutableBag<T> extends MutableBagIterable<T>, Bag<T>
132
ImmutableBag<T> extends Bag<T>
133

134
// Sorted bag operations
135
SortedBag<T> extends Bag<T>, SortedIterable<T>
136
MutableSortedBag<T> extends MutableBag<T>, SortedBag<T>
137
ImmutableSortedBag<T> extends SortedBag<T>
138

139
// Stack operations (LIFO collections)
140
StackIterable<T> extends OrderedIterable<T>
141
MutableStack<T> extends MutableCollection<T>, StackIterable<T>
142
ImmutableStack<T> extends StackIterable<T>
143
```
144

145
### [Maps and Multimaps](maps-multimaps.md)
146
Advanced key-value collections including traditional maps, sorted maps, multimaps for one-to-many relationships, and bidirectional maps.
147

148
```java { .api }
149
// Map operations with rich functional programming
150
MapIterable<K,V>
151
MutableMap<K,V> extends Map<K,V>, MapIterable<K,V>
152
ImmutableMap<K,V> extends MapIterable<K,V>
153

154
// Sorted map operations
155
SortedMapIterable<K,V> extends MapIterable<K,V>
156
MutableSortedMap<K,V> extends MutableMap<K,V>, SortedMap<K,V>, SortedMapIterable<K,V>
157
ImmutableSortedMap<K,V> extends SortedMapIterable<K,V>
158

159
// One-to-many key-value associations
160
Multimap<K,V>
161
MutableMultimap<K,V> extends Multimap<K,V>
162
ImmutableMultimap<K,V> extends Multimap<K,V>
163

164
// Bidirectional one-to-one mapping
165
BiMap<K,V> extends MapIterable<K,V>
166
MutableBiMap<K,V> extends BiMap<K,V>, MutableMap<K,V>
167
ImmutableBiMap<K,V> extends BiMap<K,V>, ImmutableMap<K,V>
168
```
169

170
### [Primitive Collections](primitive-collections.md)
171
Memory-efficient primitive collections for all 8 Java primitive types, avoiding boxing overhead.
172

173
```java { .api }
174
// Primitive iterables (base interfaces)
175
BooleanIterable, ByteIterable, CharIterable, DoubleIterable
176
FloatIterable, IntIterable, LongIterable, ShortIterable
177

178
// Primitive collections (example with int)
179
MutableIntList extends IntIterable
180
ImmutableIntList extends IntIterable
181
MutableIntSet extends IntIterable
182
IntIntMap // primitive-to-primitive maps
183
ObjectIntMap<K> // object-to-primitive maps
184
IntObjectMap<V> // primitive-to-object maps
185
```
186

187
### [Functional Interfaces](functional-interfaces.md)
188
Rich functional programming support with Functions, Predicates, and Procedures for both object and primitive types.
189

190
```java { .api }
191
// Core functional interfaces
192
Function<T,V> extends java.util.function.Function<T,V>
193
Function2<T1,T2,V>
194
Function0<V>
195

196
Predicate<T> extends java.util.function.Predicate<T>
197
Predicate2<T,P>
198

199
Procedure<T>
200
Procedure2<T,P>
201

202
// Primitive function interfaces
203
IntFunction<T>
204
IntToObjectFunction<V>
205
IntToIntFunction
206
ObjectIntPredicate<T>
207
IntProcedure
208
```
209

210
### Lazy and Parallel Processing
211

212
Memory-efficient lazy evaluation and parallel processing capabilities for high-performance operations.
213

214
```java { .api }
215
// Lazy evaluation for deferred computation
216
LazyIterable<T> extends RichIterable<T>
217

218
// Parallel processing with thread-safe operations
219
ParallelIterable<T>
220
```
221

222
### Ordered Collections Hierarchy
223

224
Base interfaces providing ordering and sorting capabilities across all collection types.
225

226
```java { .api }
227
// Base ordering interfaces
228
OrderedIterable<T> extends RichIterable<T>
229
ReversibleIterable<T> extends OrderedIterable<T>
230
SortedIterable<T> extends OrderedIterable<T>
231
```
232

233
### Tuple Support
234

235
Tuple types for grouping related values with compile-time type safety.
236

237
```java { .api }
238
// Core tuple interfaces
239
Pair<T1, T2> extends Serializable, Comparable<Pair<T1, T2>>
240
Triple<T1, T2, T3> extends Serializable, Comparable<Triple<T1, T2, T3>>
241
Twin<T> extends Pair<T, T>
242
Triplet<T> extends Triple<T, T, T>
243
```
244

245
### [Factories and Utilities](factories-utilities.md)
246
Factory classes and utility interfaces for convenient collection creation and manipulation.
247

248
```java { .api }
249
// Static factory classes
250
Lists.mutable, Lists.immutable, Lists.fixedSize
251
Sets.mutable, Sets.immutable, Sets.fixedSize
252
Maps.mutable, Maps.immutable, Maps.fixedSize
253
Bags.mutable, Bags.immutable
254
Stacks.mutable, Stacks.immutable
255

256
// Factory interfaces
257
MutableListFactory
258
ImmutableListFactory
259
MutableSetFactory
260
ImmutableSetFactory
261
```
262

263
## Key Features
264

265
- **Rich Functional Programming**: Comprehensive lambda-based operations (select, collect, reject, detect, partition)
266
- **Immutable Collections**: Thread-safe collections where operations return new instances
267
- **Primitive Support**: Complete primitive collection support for all 8 Java primitive types
268
- **Lazy Evaluation**: Deferred computation via LazyIterable for memory-efficient processing
269
- **Parallel Processing**: Built-in parallel execution capabilities via ParallelIterable
270
- **Sorted Collections**: Full support for sorted variants of Lists, Sets, Bags, and Maps
271
- **Tuple Support**: Type-safe grouping with Pair, Triple, Twin, and Triplet interfaces
272
- **Mathematical Set Operations**: Union, intersection, difference, symmetric difference
273
- **Occurrence Counting**: Bag collections for multiset operations
274
- **Advanced Maps**: Multimaps for one-to-many relationships, BiMaps for bidirectional mapping
275

276
## Architecture
277

278
Eclipse Collections uses a consistent design pattern across all collection types:
279

280
1. **Base Iterable**: Core functional operations (RichIterable, LazyIterable)
281
2. **Type-specific Iterables**: Collection-specific operations (ListIterable, SetIterable, etc.)
282
3. **Mutable Variants**: Modifiable collections extending Java standard interfaces
283
4. **Immutable Variants**: Thread-safe collections with transformation operations
284
5. **Factory Pattern**: Convenient creation through static factory classes
285

286
## Related Documentation
287

288
- [Core Collections](core-collections.md) - Lists, Sets, Bags, Stacks
289
- [Maps and Multimaps](maps-multimaps.md) - Key-value collections
290
- [Primitive Collections](primitive-collections.md) - Memory-efficient primitive types
291
- [Functional Interfaces](functional-interfaces.md) - Lambda support and functional programming
292
- [Factories and Utilities](factories-utilities.md) - Collection creation and utilities