0
# Core Collection Interfaces
1

2
Eclipse Collections provides a comprehensive hierarchy of collection interfaces built around the `RichIterable` foundation. This hierarchy includes both mutable and immutable variants for all collection types, offering over 200 methods for functional programming operations.
3

4
## Capabilities
5

6
### Root Interfaces
7

8
Base interfaces that form the foundation of all Eclipse Collections.
9

10
```java { .api }
11
/**
12
 * Base interface for all Eclipse Collections providing iteration capabilities
13
 */
14
interface InternalIterable<T> {
15
    /**
16
     * Execute procedure for each element
17
     * @param procedure procedure to execute
18
     */
19
    void forEach(Procedure<? super T> procedure);
20
    
21
    /**
22
     * Execute procedure for each element with additional parameter
23
     * @param procedure procedure to execute  
24
     * @param parameter additional parameter passed to procedure
25
     */
26
    <P> void forEachWith(Procedure2<? super T, ? super P> procedure, P parameter);
27
    
28
    /**
29
     * Execute procedure for each element with index
30
     * @param objectIntProcedure procedure receiving element and index
31
     */
32
    void forEachWithIndex(ObjectIntProcedure<? super T> objectIntProcedure);
33
}
34

35
/**
36
 * Primary read-only interface extending InternalIterable with rich functionality
37
 * Provides over 200 methods for functional programming operations
38
 */
39
interface RichIterable<T> extends InternalIterable<T> {
40
    // Size and testing methods
41
    int size();
42
    boolean isEmpty();
43
    boolean notEmpty();
44
    
45
    // Element testing
46
    boolean contains(Object object);
47
    boolean containsAll(Collection<?> source);
48
    boolean containsAllArguments(Object... elements);
49
    
50
    // Predicate testing  
51
    boolean anySatisfy(Predicate<? super T> predicate);
52
    boolean allSatisfy(Predicate<? super T> predicate);
53
    boolean noneSatisfy(Predicate<? super T> predicate);
54
    <P> boolean anySatisfyWith(Predicate2<? super T, ? super P> predicate, P parameter);
55
    <P> boolean allSatisfyWith(Predicate2<? super T, ? super P> predicate, P parameter);
56
    <P> boolean noneSatisfyWith(Predicate2<? super T, ? super P> predicate, P parameter);
57
    
58
    // Counting
59
    int count(Predicate<? super T> predicate);
60
    <P> int countWith(Predicate2<? super T, ? super P> predicate, P parameter);
61
    <V> Bag<V> countBy(Function<? super T, ? extends V> function);
62
    <V, P> Bag<V> countByWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
63
    
64
    // Element retrieval
65
    T getFirst();
66
    T getLast();
67
    T getAny();
68
    T getOnly();
69
    
70
    // Detection/finding
71
    T detect(Predicate<? super T> predicate);
72
    <P> T detectWith(Predicate2<? super T, ? super P> predicate, P parameter);
73
    Optional<T> detectOptional(Predicate<? super T> predicate);
74
    <P> Optional<T> detectOptionalWith(Predicate2<? super T, ? super P> predicate, P parameter);
75
    T detectIfNone(Predicate<? super T> predicate, Function0<? extends T> function);
76
    <P> T detectWithIfNone(Predicate2<? super T, ? super P> predicate, P parameter, Function0<? extends T> function);
77
    
78
    // Min/Max operations
79
    T min(Comparator<? super T> comparator);
80
    T max(Comparator<? super T> comparator);  
81
    T min();
82
    T max();
83
    <V extends Comparable<? super V>> T minBy(Function<? super T, ? extends V> function);
84
    <V extends Comparable<? super V>> T maxBy(Function<? super T, ? extends V> function);
85
    
86
    // Filtering operations
87
    RichIterable<T> select(Predicate<? super T> predicate);
88
    <P> RichIterable<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
89
    RichIterable<T> reject(Predicate<? super T> predicate);
90
    <P> RichIterable<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
91
    <S> RichIterable<S> selectInstancesOf(Class<S> clazz);
92
    
93
    // Partitioning
94
    PartitionIterable<T> partition(Predicate<? super T> predicate);
95
    <P> PartitionIterable<T> partitionWith(Predicate2<? super T, ? super P> predicate, P parameter);
96
    
97
    // Transformation operations
98
    <V> RichIterable<V> collect(Function<? super T, ? extends V> function);
99
    <P, V> RichIterable<V> collectWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
100
    <V> RichIterable<V> collectIf(Predicate<? super T> predicate, Function<? super T, ? extends V> function);
101
    <V> RichIterable<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
102
    
103
    // Primitive collection operations
104
    BooleanIterable collectBoolean(BooleanFunction<? super T> booleanFunction);
105
    ByteIterable collectByte(ByteFunction<? super T> byteFunction);
106
    CharIterable collectChar(CharFunction<? super T> charFunction);
107
    DoubleIterable collectDouble(DoubleFunction<? super T> doubleFunction);
108
    FloatIterable collectFloat(FloatFunction<? super T> floatFunction);
109
    IntIterable collectInt(IntFunction<? super T> intFunction);
110
    LongIterable collectLong(LongFunction<? super T> longFunction);
111
    ShortIterable collectShort(ShortFunction<? super T> shortFunction);
112
    
113
    // Grouping operations
114
    <V> Multimap<V, T> groupBy(Function<? super T, ? extends V> function);
115
    <V> Multimap<V, T> groupByEach(Function<? super T, ? extends Iterable<V>> function);
116
    <V> MapIterable<V, T> groupByUniqueKey(Function<? super T, ? extends V> function);
117
    
118
    // Aggregation operations
119
    <IV> IV injectInto(IV injectedValue, Function2<? super IV, ? super T, ? extends IV> function);
120
    <P, IV> IV injectIntoWith(IV injectedValue, Function3<? super IV, ? super T, ? super P, ? extends IV> function, P parameter);
121
    
122
    // Numeric aggregations
123
    long sumOfInt(IntFunction<? super T> function);
124
    double sumOfFloat(FloatFunction<? super T> function);
125
    long sumOfLong(LongFunction<? super T> function);
126
    double sumOfDouble(DoubleFunction<? super T> function);
127
    
128
    // Java 8 Stream integration
129
    Optional<T> reduce(BinaryOperator<T> accumulator);
130
    T reduce(T identity, BinaryOperator<T> accumulator);
131
    <U> U reduce(U identity, BiFunction<U, ? super T, U> accumulator, BinaryOperator<U> combiner);
132
    
133
    // Advanced aggregation
134
    <K, V> MapIterable<K, V> aggregateInPlaceBy(
135
        Function<? super T, ? extends K> groupBy,
136
        Function0<? extends V> zeroValueFactory,
137
        Procedure2<? super V, ? super T> mutatingAggregator);
138
    
139
    <K, V> MapIterable<K, V> aggregateBy(
140
        Function<? super T, ? extends K> groupBy,
141
        Function0<? extends V> zeroValueFactory,
142
        Function2<? super V, ? super T, ? extends V> nonMutatingAggregator);
143
    
144
    // Utility methods
145
    RichIterable<RichIterable<T>> chunk(int size);
146
    RichIterable<T> tap(Procedure<? super T> procedure);
147
    void each(Procedure<? super T> procedure);
148
    <P> void forEachWith(Procedure2<? super T, ? super P> procedure, P parameter);
149
    
150
    // Lazy evaluation
151
    LazyIterable<T> asLazy();
152
    
153
    // Conversion methods
154
    MutableList<T> toList();
155
    MutableList<T> toSortedList();
156
    MutableList<T> toSortedList(Comparator<? super T> comparator);
157
    <V extends Comparable<? super V>> MutableList<T> toSortedListBy(Function<? super T, ? extends V> function);
158
    
159
    MutableSet<T> toSet();
160
    MutableSortedSet<T> toSortedSet();
161
    MutableSortedSet<T> toSortedSet(Comparator<? super T> comparator);
162
    <V extends Comparable<? super V>> MutableSortedSet<T> toSortedSetBy(Function<? super T, ? extends V> function);
163
    
164
    MutableBag<T> toBag();
165
    MutableSortedBag<T> toSortedBag();
166
    MutableSortedBag<T> toSortedBag(Comparator<? super T> comparator);
167
    <V extends Comparable<? super V>> MutableSortedBag<T> toSortedBagBy(Function<? super T, ? extends V> function);
168
    
169
    <NK, NV> MutableMap<NK, NV> toMap(Function<? super T, ? extends NK> keyFunction, Function<? super T, ? extends NV> valueFunction);
170
    <NK, NV> MutableSortedMap<NK, NV> toSortedMap(Function<? super T, ? extends NK> keyFunction, Function<? super T, ? extends NV> valueFunction);
171
    <NK, NV> MutableSortedMap<NK, NV> toSortedMap(Comparator<? super NK> comparator, Function<? super T, ? extends NK> keyFunction, Function<? super T, ? extends NV> valueFunction);
172
    
173
    // Immutable conversion methods  
174
    ImmutableList<T> toImmutableList();
175
    ImmutableSet<T> toImmutableSet();
176
    ImmutableBag<T> toImmutableBag();
177
    ImmutableSortedSet<T> toImmutableSortedSet();
178
    ImmutableSortedSet<T> toImmutableSortedSet(Comparator<? super T> comparator);
179
    ImmutableSortedBag<T> toImmutableSortedBag();
180
    ImmutableSortedBag<T> toImmutableSortedBag(Comparator<? super T> comparator);
181
    
182
    // Array conversion
183
    Object[] toArray();
184
    <E> E[] toArray(E[] array);
185
    
186
    // String methods
187
    String makeString();
188
    String makeString(String separator);
189
    String makeString(String start, String separator, String end);
190
    void appendString(Appendable appendable);
191
    void appendString(Appendable appendable, String separator);
192
    void appendString(Appendable appendable, String start, String separator, String end);
193
}
194
```
195

196
**Usage Examples:**
197

198
```java
199
import org.eclipse.collections.api.RichIterable;
200
import org.eclipse.collections.impl.factory.Lists;
201

202
MutableList<Person> people = Lists.mutable.with(
203
    new Person("Alice", 25),
204
    new Person("Bob", 30),  
205
    new Person("Charlie", 35)
206
);
207

208
// Filtering operations
209
RichIterable<Person> adults = people.select(person -> person.getAge() >= 18);
210
RichIterable<Person> youngAdults = people.selectWith((person, minAge) -> person.getAge() >= minAge, 21);
211

212
// Transformation operations
213
RichIterable<String> names = people.collect(Person::getName);
214
RichIterable<String> upperCaseNames = people.collect(person -> person.getName().toUpperCase());
215

216
// Aggregation operations  
217
int totalAge = people.sumOfInt(Person::getAge);
218
Person oldest = people.maxBy(Person::getAge);
219
String allNames = people.collect(Person::getName).makeString(", ");
220

221
// Counting and testing
222
int adultsCount = people.count(person -> person.getAge() >= 18);
223
boolean hasMinors = people.anySatisfy(person -> person.getAge() < 18);
224
boolean allAdults = people.allSatisfy(person -> person.getAge() >= 18);
225

226
// Grouping
227
Multimap<Integer, Person> peopleByAge = people.groupBy(Person::getAge);
228
MapIterable<String, Person> peopleByName = people.groupByUniqueKey(Person::getName);
229
```
230

231
### Lazy Evaluation Interface
232

233
Interface for lazy evaluation providing deferred computation.
234

235
```java { .api }
236
/**
237
 * Lazy evaluation iterable for deferred computation
238
 * Operations are not executed until a terminal operation is called
239
 */
240
interface LazyIterable<T> extends RichIterable<T> {
241
    /**
242
     * Force evaluation and return eager iterable
243
     * @return RichIterable with computed results
244
     */
245
    RichIterable<T> eager();
246
    
247
    /**
248
     * Get size by forcing evaluation  
249
     * @return computed size
250
     */
251
    int size();
252
    
253
    /**
254
     * Convert to array by forcing evaluation
255
     * @return computed array
256
     */
257
    Object[] toArray();
258
    
259
    /**
260
     * Force evaluation and return list
261
     * @return MutableList with computed results  
262
     */
263
    MutableList<T> toList();
264
    
265
    /**
266
     * Force evaluation and return set
267
     * @return MutableSet with computed results
268
     */
269
    MutableSet<T> toSet();
270
    
271
    /**
272
     * Force evaluation and return bag
273
     * @return MutableBag with computed results
274
     */
275
    MutableBag<T> toBag();
276
}
277
```
278

279
### Parallel Processing Interface
280

281
Interface for parallel processing operations.
282

283
```java { .api }
284
/**
285
 * Interface for parallel processing operations
286
 * Provides parallelized versions of common operations
287
 */
288
interface ParallelIterable<T> extends RichIterable<T> {
289
    /**
290
     * Execute procedure in parallel for each element
291
     * @param procedure procedure to execute
292
     */
293
    void forEach(Procedure<? super T> procedure);
294
    
295
    /**
296
     * Parallel select operation
297
     * @param predicate predicate for filtering
298
     * @return ParallelIterable with selected elements
299
     */
300
    ParallelIterable<T> select(Predicate<? super T> predicate);
301
    
302
    /**
303
     * Parallel reject operation
304
     * @param predicate predicate for filtering  
305
     * @return ParallelIterable with rejected elements
306
     */
307
    ParallelIterable<T> reject(Predicate<? super T> predicate);
308
    
309
    /**
310
     * Parallel collect operation
311
     * @param function transformation function
312
     * @return ParallelIterable with transformed elements
313
     */
314
    <V> ParallelIterable<V> collect(Function<? super T, ? extends V> function);
315
    
316
    /**
317
     * Parallel flat collect operation
318
     * @param function function returning iterables
319
     * @return ParallelIterable with flattened results
320
     */
321
    <V> ParallelIterable<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
322
}
323
```
324

325
### Collection Base Interfaces
326

327
Base interfaces for mutable and immutable collections.
328

329
```java { .api }
330
/**
331
 * Base mutable collection interface extending JDK Collection
332
 * Provides fluent API methods and Eclipse Collections functionality
333
 */
334
interface MutableCollection<T> extends Collection<T>, RichIterable<T> {
335
    // Modification operations
336
    boolean add(T item);
337
    boolean remove(Object item);
338
    boolean addAll(Collection<? extends T> source);
339
    boolean addAllIterable(Iterable<? extends T> iterable);
340
    boolean removeAll(Collection<?> collection);
341
    boolean retainAll(Collection<?> collection);
342
    void clear();
343
    
344
    // Fluent API methods
345
    MutableCollection<T> with(T element);
346
    MutableCollection<T> without(T element);
347
    MutableCollection<T> withAll(Iterable<? extends T> elements);
348
    MutableCollection<T> withoutAll(Iterable<? extends T> elements);
349
    
350
    // Mutable filtering operations return new collections
351
    MutableCollection<T> select(Predicate<? super T> predicate);
352
    <P> MutableCollection<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
353
    MutableCollection<T> reject(Predicate<? super T> predicate);
354
    <P> MutableCollection<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
355
    
356
    // Mutable transformation operations
357
    <V> MutableCollection<V> collect(Function<? super T, ? extends V> function);
358
    <P, V> MutableCollection<V> collectWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
359
    <V> MutableCollection<V> collectIf(Predicate<? super T> predicate, Function<? super T, ? extends V> function);
360
    <V> MutableCollection<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
361
    
362
    // Iterator with removal support
363
    Iterator<T> iterator();
364
    
365
    // Parallel processing  
366
    ParallelIterable<T> asParallel(ExecutorService executorService, int batchSize);
367
}
368

369
/**
370
 * Base immutable collection interface  
371
 * All modification operations return new immutable instances
372
 */
373
interface ImmutableCollection<T> extends RichIterable<T> {
374
    /**
375
     * Create new collection with additional element
376
     * @param element element to add
377
     * @return new ImmutableCollection with element added
378
     */
379
    ImmutableCollection<T> newWith(T element);
380
    
381
    /**
382
     * Create new collection with multiple additional elements
383
     * @param elements elements to add
384
     * @return new ImmutableCollection with elements added
385
     */
386
    ImmutableCollection<T> newWithAll(Iterable<? extends T> elements);
387
    
388
    /**
389
     * Create new collection without specified element  
390
     * @param element element to remove
391
     * @return new ImmutableCollection with element removed
392
     */
393
    ImmutableCollection<T> newWithout(T element);
394
    
395
    /**
396
     * Create new collection without specified elements
397
     * @param elements elements to remove
398
     * @return new ImmutableCollection with elements removed  
399
     */
400
    ImmutableCollection<T> newWithoutAll(Iterable<? extends T> elements);
401
    
402
    // Immutable filtering operations
403
    ImmutableCollection<T> select(Predicate<? super T> predicate);
404
    <P> ImmutableCollection<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
405
    ImmutableCollection<T> reject(Predicate<? super T> predicate);
406
    <P> ImmutableCollection<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
407
    
408
    // Immutable transformation operations  
409
    <V> ImmutableCollection<V> collect(Function<? super T, ? extends V> function);
410
    <P, V> ImmutableCollection<V> collectWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
411
    <V> ImmutableCollection<V> collectIf(Predicate<? super T> predicate, Function<? super T, ? extends V> function);
412
    <V> ImmutableCollection<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
413
}
414
```
415

416
## List Interfaces
417

418
Comprehensive list interfaces providing indexed access and ordering.
419

420
```java { .api }
421
/**
422
 * Base list interface providing indexed access and ordering
423
 */
424
interface ListIterable<T> extends RichIterable<T>, OrderedIterable<T> {
425
    // Indexed access
426
    T get(int index);
427
    
428
    // Index-based search  
429
    int indexOf(Object object);
430
    int lastIndexOf(Object object);
431
    
432
    // List-specific operations
433
    ListIterable<T> select(Predicate<? super T> predicate);
434
    <P> ListIterable<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
435
    ListIterable<T> reject(Predicate<? super T> predicate);
436
    <P> ListIterable<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
437
    
438
    <V> ListIterable<V> collect(Function<? super T, ? extends V> function);
439
    <P, V> ListIterable<V> collectWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
440
    <V> ListIterable<V> collectIf(Predicate<? super T> predicate, Function<? super T, ? extends V> function);
441
    <V> ListIterable<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
442
    
443
    // Partitioning
444
    PartitionList<T> partition(Predicate<? super T> predicate);
445
    <P> PartitionList<T> partitionWith(Predicate2<? super T, ? super P> predicate, P parameter);
446
    
447
    // List conversion
448
    MutableList<T> toList();
449
    ImmutableList<T> toImmutableList();
450
}
451

452
/**
453
 * Mutable list interface extending JDK List
454
 */
455
interface MutableList<T> extends MutableCollection<T>, List<T>, ListIterable<T>, Cloneable {
456
    // JDK List operations
457
    void add(int index, T element);
458
    boolean addAll(int index, Collection<? extends T> collection);
459
    T get(int index);
460
    T set(int index, T element);
461
    T remove(int index);
462
    
463
    // Eclipse Collections enhancements
464
    MutableList<T> with(T element);
465
    MutableList<T> without(T element);
466
    MutableList<T> withAll(Iterable<? extends T> elements);
467
    MutableList<T> withoutAll(Iterable<? extends T> elements);
468
    
469
    // In-place operations
470
    MutableList<T> sortThis();
471
    MutableList<T> sortThis(Comparator<? super T> comparator);
472
    <V extends Comparable<? super V>> MutableList<T> sortThisBy(Function<? super T, ? extends V> function);
473
    MutableList<T> reverseThis();
474
    MutableList<T> shuffleThis();
475
    MutableList<T> shuffleThis(Random rnd);
476
    
477
    // Sublist operations
478
    MutableList<T> subList(int fromIndex, int toIndex);
479
    
480
    // Mutable list-specific transformations
481
    MutableList<T> select(Predicate<? super T> predicate);
482
    <P> MutableList<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
483
    MutableList<T> reject(Predicate<? super T> predicate);
484
    <P> MutableList<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
485
    
486
    <V> MutableList<V> collect(Function<? super T, ? extends V> function);
487
    <P, V> MutableList<V> collectWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
488
    <V> MutableList<V> collectIf(Predicate<? super T> predicate, Function<? super T, ? extends V> function);
489
    <V> MutableList<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
490
    
491
    // Iterator with modification support
492
    ListIterator<T> listIterator();
493
    ListIterator<T> listIterator(int index);
494
    
495
    // Clone support
496
    MutableList<T> clone();
497
}
498

499
/**
500
 * Immutable list interface
501
 */
502
interface ImmutableList<T> extends ImmutableCollection<T>, ListIterable<T> {
503
    // Immutable modification operations
504
    ImmutableList<T> newWith(T element);
505
    ImmutableList<T> newWithAll(Iterable<? extends T> elements);
506
    ImmutableList<T> newWithout(T element);
507
    ImmutableList<T> newWithoutAll(Iterable<? extends T> elements);
508
    
509
    // Immutable transformations
510
    ImmutableList<T> select(Predicate<? super T> predicate);
511
    <P> ImmutableList<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
512
    ImmutableList<T> reject(Predicate<? super T> predicate);
513
    <P> ImmutableList<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
514
    
515
    <V> ImmutableList<V> collect(Function<? super T, ? extends V> function);
516
    <P, V> ImmutableList<V> collectWith(Function2<? super T, ? super P, ? extends V> function, P parameter);
517
    <V> ImmutableList<V> collectIf(Predicate<? super T> predicate, Function<? super T, ? extends V> function);
518
    <V> ImmutableList<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
519
}
520

521
/**
522
 * Fixed-size list interface - cannot be resized
523
 */
524
interface FixedSizeList<T> extends MutableList<T> {
525
    // All modification operations that change size throw UnsupportedOperationException
526
    // Available: set, sort, reverse, shuffle operations
527
    // Not available: add, remove, clear operations
528
}
529
```
530

531
## Set Interfaces
532

533
Set interfaces providing unique element collections with set algebra operations.
534

535
```java { .api }
536
/**
537
 * Base set interface providing set-specific operations
538
 */
539
interface SetIterable<T> extends RichIterable<T> {
540
    // Set algebra operations
541
    SetIterable<T> union(SetIterable<? extends T> set);
542
    SetIterable<T> intersect(SetIterable<? extends T> set);
543
    SetIterable<T> difference(SetIterable<? extends T> subtrahend);
544
    SetIterable<T> symmetricDifference(SetIterable<? extends T> set);
545
    
546
    // Subset operations
547
    boolean isSubsetOf(SetIterable<? extends T> candidateSuperset);
548
    boolean isProperSubsetOf(SetIterable<? extends T> candidateSuperset);
549
    
550
    // Power set
551
    SetIterable<SetIterable<T>> powerSet();
552
    
553
    // Cartesian product
554
    <B> LazyIterable<Pair<T, B>> cartesianProduct(SetIterable<B> set);
555
    
556
    // Set-specific transformations
557
    SetIterable<T> select(Predicate<? super T> predicate);
558
    <P> SetIterable<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
559
    SetIterable<T> reject(Predicate<? super T> predicate);
560
    <P> SetIterable<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
561
    
562
    <V> SetIterable<V> collect(Function<? super T, ? extends V> function);
563
    <V> SetIterable<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
564
}
565

566
/**
567
 * Mutable set interface extending JDK Set
568
 */
569
interface MutableSet<T> extends MutableCollection<T>, Set<T>, SetIterable<T>, Cloneable {
570
    // Fluent API
571
    MutableSet<T> with(T element);
572
    MutableSet<T> without(T element);
573
    MutableSet<T> withAll(Iterable<? extends T> elements);
574
    MutableSet<T> withoutAll(Iterable<? extends T> elements);
575
    
576
    // Mutable set algebra operations (modify this set)
577
    boolean unionInto(SetIterable<? extends T> set, MutableSet<T> targetSet);
578
    boolean intersectInto(SetIterable<? extends T> set, MutableSet<T> targetSet);
579
    boolean differenceInto(SetIterable<? extends T> subtrahend, MutableSet<T> targetSet);
580
    boolean symmetricDifferenceInto(SetIterable<? extends T> set, MutableSet<T> targetSet);
581
    
582
    // Mutable set transformations
583
    MutableSet<T> select(Predicate<? super T> predicate);
584
    <P> MutableSet<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
585
    MutableSet<T> reject(Predicate<? super T> predicate);
586
    <P> MutableSet<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
587
    
588
    <V> MutableSet<V> collect(Function<? super T, ? extends V> function);
589
    <V> MutableSet<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
590
    
591
    // Clone support
592
    MutableSet<T> clone();
593
}
594

595
/**
596
 * Immutable set interface
597
 */
598
interface ImmutableSet<T> extends ImmutableCollection<T>, SetIterable<T> {
599
    // Immutable modification operations
600
    ImmutableSet<T> newWith(T element);
601
    ImmutableSet<T> newWithAll(Iterable<? extends T> elements);
602
    ImmutableSet<T> newWithout(T element);
603
    ImmutableSet<T> newWithoutAll(Iterable<? extends T> elements);
604
    
605
    // Immutable transformations
606
    ImmutableSet<T> select(Predicate<? super T> predicate);
607
    <P> ImmutableSet<T> selectWith(Predicate2<? super T, ? super P> predicate, P parameter);
608
    ImmutableSet<T> reject(Predicate<? super T> predicate);
609
    <P> ImmutableSet<T> rejectWith(Predicate2<? super T, ? super P> predicate, P parameter);
610
    
611
    <V> ImmutableSet<V> collect(Function<? super T, ? extends V> function);
612
    <V> ImmutableSet<V> flatCollect(Function<? super T, ? extends Iterable<V>> function);
613
}
614
```
615

616
## Map Interfaces
617

618
Comprehensive map interfaces providing key-value collections with rich operations.
619

620
```java { .api }
621
/**
622
 * Base map interface extending RichIterable over values
623
 */
624
interface MapIterable<K, V> extends RichIterable<V> {
625
    // Basic map operations
626
    V get(Object key);
627
    boolean containsKey(Object key);
628
    boolean containsValue(Object value);
629
    
630
    // Enhanced get operations
631
    V getIfAbsent(K key, Function0<? extends V> function);
632
    V getIfAbsentValue(K key, V defaultValue);
633
    <P> V getIfAbsentWith(K key, Function<? super P, ? extends V> function, P parameter);
634
    
635
    // Views
636
    RichIterable<K> keysView();
637
    RichIterable<V> valuesView();
638
    RichIterable<Pair<K, V>> keyValuesView();
639
    
640
    // Map-specific operations
641
    <R> RichIterable<R> collect(Function2<? super K, ? super V, ? extends R> function);
642
    <R> RichIterable<R> collectValues(Function<? super V, ? extends R> function);
643
    MapIterable<K, V> select(Predicate2<? super K, ? super V> predicate);
644
    MapIterable<K, V> reject(Predicate2<? super K, ? super V> predicate);
645
    
646
    // Conversion
647
    MutableMap<K, V> toMap();
648
    ImmutableMap<K, V> toImmutable();
649
}
650

651
/**
652
 * Mutable map interface extending JDK Map
653
 */
654
interface MutableMap<K, V> extends MutableMapIterable<K, V>, Map<K, V>, Cloneable {
655
    // JDK Map operations
656
    V put(K key, V value);
657
    void putAll(Map<? extends K, ? extends V> map);
658
    V remove(Object key);
659
    void clear();
660
    
661
    // Enhanced put operations
662
    V getIfAbsentPut(K key, Function0<? extends V> function);
663
    V getIfAbsentPutValue(K key, V value);
664
    <P> V getIfAbsentPutWith(K key, Function<? super P, ? extends V> function, P parameter);
665
    V getIfAbsentPutWithKey(K key, Function<? super K, ? extends V> function);
666
    
667
    // Update operations
668
    V updateValue(K key, Function0<? extends V> factory, Function<? super V, ? extends V> function);
669
    <P> V updateValueWith(K key, Function0<? extends V> factory, Function2<? super V, ? super P, ? extends V> function, P parameter);
670
    
671
    // Fluent API
672
    MutableMap<K, V> withKeyValue(K key, V value);
673
    MutableMap<K, V> withAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValuePairs);
674
    MutableMap<K, V> withAllKeyValueArguments(Pair<? extends K, ? extends V>... keyValuePairs);
675
    MutableMap<K, V> withoutKey(K key);
676
    MutableMap<K, V> withoutAllKeys(Iterable<? extends K> keys);
677
    
678
    // Mutable transformations
679
    MutableMap<K, V> select(Predicate2<? super K, ? super V> predicate);
680
    MutableMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
681
    <R> MutableCollection<R> collect(Function2<? super K, ? super V, ? extends R> function);
682
    
683
    // Clone support
684
    MutableMap<K, V> clone();
685
}
686

687
/**
688
 * Immutable map interface
689
 */
690
interface ImmutableMap<K, V> extends MapIterable<K, V> {
691
    // Immutable modification operations
692
    ImmutableMap<K, V> newWithKeyValue(K key, V value);
693
    ImmutableMap<K, V> newWithAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
694
    ImmutableMap<K, V> newWithAllKeyValueArguments(Pair<? extends K, ? extends V>... keyValuePairs);
695
    ImmutableMap<K, V> newWithoutKey(K key);
696
    ImmutableMap<K, V> newWithoutAllKeys(Iterable<? extends K> keys);
697
    
698
    // Immutable transformations
699
    ImmutableMap<K, V> select(Predicate2<? super K, ? super V> predicate);
700
    ImmutableMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
701
}
702
```
703

704
## Design Principles
705

706
### Consistency
707

708
All collection interfaces follow consistent design patterns:
709

710
1. **Method naming**: `select/reject` for filtering, `collect` for transformation
711
2. **Fluent API**: Methods return the same collection type for chaining
712
3. **Immutable variants**: All modification operations return new instances
713
4. **Parameter variants**: `With` methods for parameterized operations
714

715
### Performance
716

717
- **Lazy evaluation**: `asLazy()` provides deferred computation
718
- **Parallel processing**: `asParallel()` enables concurrent operations  
719
- **Memory efficiency**: Optimized implementations with lower overhead
720
- **Primitive specializations**: Avoid boxing with primitive collections
721

722
### Type Safety
723

724
- **Generic preservation**: Type information maintained through transformations  
725
- **Covariant returns**: Methods return most specific collection type
726
- **Compile-time safety**: Strong typing prevents runtime errors