0
# Collections and Utilities
1

2
Apache Fury provides high-performance collection implementations and utility classes optimized for serialization use cases and general-purpose operations.
3

4
## High-Performance Collections
5

6
### FuryObjectMap
7

8
High-performance object-to-object map optimized for serialization scenarios.
9

10
```java { .api }
11
public class FuryObjectMap<K, V> {
12
    // Constructors
13
    public FuryObjectMap();
14
    public FuryObjectMap(int initialCapacity);
15
    public FuryObjectMap(int initialCapacity, float loadFactor);
16
    
17
    // Map operations
18
    public V put(K key, V value);
19
    public V get(Object key);
20
    public V remove(Object key);
21
    public boolean containsKey(Object key);
22
    public boolean containsValue(Object value);
23
    
24
    // Bulk operations
25
    public void putAll(Map<? extends K, ? extends V> map);
26
    public void clear();
27
    
28
    // Size and state
29
    public int size();
30
    public boolean isEmpty();
31
    
32
    // Views
33
    public Set<K> keySet();
34
    public Collection<V> values();
35
    public Set<Map.Entry<K, V>> entrySet();
36
    
37
    // Performance optimizations
38
    public void ensureCapacity(int capacity);
39
    public void trimToSize();
40
    public MapStatistics getStatistics();
41
}
42
```
43

44
### IntArray
45

46
Primitive int array wrapper with dynamic resizing capabilities.
47

48
```java { .api }
49
public class IntArray {
50
    // Constructors
51
    public IntArray();
52
    public IntArray(int initialCapacity);
53
    public IntArray(int[] array);
54
    
55
    // Array operations
56
    public void add(int value);
57
    public void add(int index, int value);
58
    public int get(int index);
59
    public void set(int index, int value);
60
    public int remove(int index);
61
    
62
    // Bulk operations
63
    public void addAll(int[] values);
64
    public void addAll(IntArray other);
65
    public int[] toArray();
66
    public void clear();
67
    
68
    // Size and capacity
69
    public int size();
70
    public boolean isEmpty();
71
    public void ensureCapacity(int capacity);
72
    public void trimToSize();
73
    
74
    // Utilities
75
    public boolean contains(int value);
76
    public int indexOf(int value);
77
    public int lastIndexOf(int value);
78
}
79
```
80

81
### ObjectArray
82

83
Generic object array wrapper with type safety and dynamic resizing.
84

85
```java { .api }
86
public class ObjectArray<T> {
87
    // Constructors
88
    public ObjectArray(Class<T> componentType);
89
    public ObjectArray(Class<T> componentType, int initialCapacity);
90
    public ObjectArray(T[] array);
91
    
92
    // Array operations
93
    public void add(T element);
94
    public void add(int index, T element);
95
    public T get(int index);
96
    public void set(int index, T element);
97
    public T remove(int index);
98
    
99
    // Type-safe operations
100
    public T[] toArray();
101
    public T[] toArray(T[] array);
102
    public Class<T> getComponentType();
103
    
104
    // Collection-like operations
105
    public boolean contains(T element);
106
    public int indexOf(T element);
107
    public void clear();
108
    public int size();
109
    public boolean isEmpty();
110
}
111
```
112

113
## Specialized Maps
114

115
### LongMap
116

117
Primitive long-to-object map for memory-efficient storage.
118

119
```java { .api }
120
public class LongMap<V> {
121
    // Constructors
122
    public LongMap();
123
    public LongMap(int initialCapacity);
124
    
125
    // Map operations
126
    public V put(long key, V value);
127
    public V get(long key);
128
    public V remove(long key);
129
    public boolean containsKey(long key);
130
    
131
    // Primitive operations
132
    public long[] keys();
133
    public V[] values();
134
    public void putAll(LongMap<? extends V> other);
135
    
136
    // Size and state
137
    public int size();
138
    public boolean isEmpty();
139
    public void clear();
140
    
141
    // Iteration
142
    public LongMapIterator<V> iterator();
143
}
144
```
145

146
### ObjectIntMap
147

148
Object-to-primitive-int map for efficient integer storage.
149

150
```java { .api }
151
public class ObjectIntMap<K> {
152
    // Constructors
153
    public ObjectIntMap();
154
    public ObjectIntMap(int initialCapacity);
155
    
156
    // Map operations
157
    public int put(K key, int value);
158
    public int get(K key);
159
    public int get(K key, int defaultValue);
160
    public int remove(K key);
161
    public boolean containsKey(K key);
162
    
163
    // Primitive specializations
164
    public int[] values();
165
    public K[] keys();
166
    public void increment(K key);
167
    public void increment(K key, int amount);
168
    
169
    // Statistics
170
    public int sum();
171
    public int max();
172
    public int min();
173
    
174
    // Size and state
175
    public int size();
176
    public boolean isEmpty();
177
    public void clear();
178
}
179
```
180

181
### IdentityMap
182

183
Identity-based map using reference equality instead of equals().
184

185
```java { .api }
186
public class IdentityMap<K, V> {
187
    // Constructors
188
    public IdentityMap();
189
    public IdentityMap(int expectedMaxSize);
190
    
191
    // Identity-based operations
192
    public V put(K key, V value);
193
    public V get(K key);
194
    public V remove(K key);
195
    public boolean containsKey(K key);  // Uses == instead of equals()
196
    
197
    // Standard map operations
198
    public void putAll(Map<? extends K, ? extends V> map);
199
    public void clear();
200
    public int size();
201
    public boolean isEmpty();
202
    
203
    // Views (maintain identity semantics)
204
    public Set<K> keySet();
205
    public Collection<V> values();
206
    public Set<Map.Entry<K, V>> entrySet();
207
}
208
```
209

210
## Tuple Classes
211

212
### Tuple2
213

214
Immutable two-element tuple.
215

216
```java { .api }
217
public class Tuple2<T0, T1> implements Serializable {
218
    public final T0 f0;
219
    public final T1 f1;
220
    
221
    // Constructor
222
    public Tuple2(T0 f0, T1 f1);
223
    
224
    // Factory methods
225
    public static <T0, T1> Tuple2<T0, T1> of(T0 f0, T1 f1);
226
    
227
    // Accessors
228
    public T0 getF0();
229
    public T1 getF1();
230
    public T0 _1();  // Scala-style accessor
231
    public T1 _2();  // Scala-style accessor
232
    
233
    // Object methods
234
    @Override
235
    public boolean equals(Object obj);
236
    @Override
237
    public int hashCode();
238
    @Override
239
    public String toString();
240
}
241
```
242

243
### Tuple3
244

245
Immutable three-element tuple.
246

247
```java { .api }
248
public class Tuple3<T0, T1, T2> implements Serializable {
249
    public final T0 f0;
250
    public final T1 f1;
251
    public final T2 f2;
252
    
253
    // Constructor
254
    public Tuple3(T0 f0, T1 f1, T2 f2);
255
    
256
    // Factory methods
257
    public static <T0, T1, T2> Tuple3<T0, T1, T2> of(T0 f0, T1 f1, T2 f2);
258
    
259
    // Accessors
260
    public T0 getF0();
261
    public T1 getF1();
262
    public T2 getF2();
263
    public T0 _1();  // Scala-style accessor
264
    public T1 _2();  // Scala-style accessor
265
    public T2 _3();  // Scala-style accessor
266
    
267
    // Object methods
268
    @Override
269
    public boolean equals(Object obj);
270
    @Override
271
    public int hashCode();
272
    @Override
273
    public String toString();
274
}
275
```
276

277
### Mutable Tuples
278

279
```java { .api }
280
public class MutableTuple2<T0, T1> implements Serializable {
281
    public T0 f0;
282
    public T1 f1;
283
    
284
    // Constructors
285
    public MutableTuple2();
286
    public MutableTuple2(T0 f0, T1 f1);
287
    
288
    // Mutators
289
    public void setF0(T0 f0);
290
    public void setF1(T1 f1);
291
    public void set(T0 f0, T1 f1);
292
    
293
    // Conversion
294
    public Tuple2<T0, T1> toImmutable();
295
}
296

297
public class MutableTuple3<T0, T1, T2> implements Serializable {
298
    public T0 f0;
299
    public T1 f1;
300
    public T2 f2;
301
    
302
    // Similar API to MutableTuple2 but with three elements
303
    public void set(T0 f0, T1 f1, T2 f2);
304
    public Tuple3<T0, T1, T2> toImmutable();
305
}
306
```
307

308
## Utility Classes
309

310
### Collections
311

312
Utility methods for working with collections.
313

314
```java { .api }
315
public class Collections {
316
    // Collection creation
317
    public static <T> List<T> ofList(T... elements);
318
    public static <T> Set<T> ofSet(T... elements);
319
    public static <K, V> Map<K, V> ofMap(K k1, V v1);
320
    public static <K, V> Map<K, V> ofMap(K k1, V v1, K k2, V v2);
321
    
322
    // Collection utilities
323
    public static boolean isEmpty(Collection<?> collection);
324
    public static boolean isNotEmpty(Collection<?> collection);
325
    public static int size(Collection<?> collection);
326
    
327
    // Collection operations
328
    public static <T> List<T> reverse(List<T> list);
329
    public static <T> List<T> concat(List<T> list1, List<T> list2);
330
    public static <T> Set<T> union(Set<T> set1, Set<T> set2);
331
    public static <T> Set<T> intersection(Set<T> set1, Set<T> set2);
332
    
333
    // Type-safe collection operations
334
    public static <T> T[] toArray(Collection<T> collection, Class<T> type);
335
    public static <T> List<T> filter(Collection<T> collection, Predicate<T> predicate);
336
    public static <T, R> List<R> map(Collection<T> collection, Function<T, R> mapper);
337
}
338
```
339

340
### LazyMap
341

342
Map implementation with lazy value computation.
343

344
```java { .api }
345
public class LazyMap<K, V> implements Map<K, V> {
346
    // Constructors
347
    public LazyMap(Function<K, V> valueComputer);
348
    public LazyMap(Map<K, V> delegate, Function<K, V> valueComputer);
349
    
350
    // Lazy computation
351
    @Override
352
    public V get(Object key);  // Computes value if not present
353
    public V getIfPresent(Object key);  // Returns null if not computed
354
    public boolean isComputed(Object key);
355
    
356
    // Force computation
357
    public V compute(K key);
358
    public void computeAll();
359
    public void computeAll(Collection<? extends K> keys);
360
    
361
    // Standard map operations
362
    @Override
363
    public V put(K key, V value);
364
    @Override
365
    public V remove(Object key);
366
    @Override
367
    public void clear();
368
    @Override
369
    public int size();
370
    @Override
371
    public boolean isEmpty();
372
}
373
```
374

375
### MultiKeyWeakMap
376

377
Weak reference map supporting multiple keys per value.
378

379
```java { .api }
380
public class MultiKeyWeakMap<T> {
381
    // Constructors
382
    public MultiKeyWeakMap();
383
    public MultiKeyWeakMap(int initialCapacity);
384
    
385
    // Multi-key operations
386
    public T put(Object[] keys, T value);
387
    public T get(Object[] keys);
388
    public T remove(Object[] keys);
389
    public boolean containsKeys(Object[] keys);
390
    
391
    // Single key operations
392
    public T put(Object key, T value);
393
    public T get(Object key);
394
    public boolean containsKey(Object key);
395
    
396
    // Weak reference management
397
    public void cleanUp();  // Manual cleanup of dead references
398
    public int size();
399
    public void clear();
400
    
401
    // Statistics
402
    public int getDeadReferenceCount();
403
    public double getLoadFactor();
404
}
405
```
406

407
## General Utilities
408

409
### Preconditions
410

411
Validation utilities for argument and state checking.
412

413
```java { .api }
414
public class Preconditions {
415
    // Null checks
416
    public static <T> T checkNotNull(T reference);
417
    public static <T> T checkNotNull(T reference, String errorMessage);
418
    public static <T> T checkNotNull(T reference, String errorMessageTemplate, Object... errorMessageArgs);
419
    
420
    // Argument validation
421
    public static void checkArgument(boolean expression);
422
    public static void checkArgument(boolean expression, String errorMessage);
423
    public static void checkArgument(boolean expression, String errorMessageTemplate, Object... errorMessageArgs);
424
    
425
    // State validation
426
    public static void checkState(boolean expression);
427
    public static void checkState(boolean expression, String errorMessage);
428
    
429
    // Index validation
430
    public static int checkElementIndex(int index, int size);
431
    public static int checkElementIndex(int index, int size, String desc);
432
    public static int checkPositionIndex(int index, int size);
433
    
434
    // Range validation
435
    public static void checkPositionIndexes(int start, int end, int size);
436
}
437
```
438

439
### StringUtils
440

441
String manipulation utilities.
442

443
```java { .api }
444
public class StringUtils {
445
    // Null-safe operations
446
    public static boolean isEmpty(String str);
447
    public static boolean isNotEmpty(String str);
448
    public static boolean isBlank(String str);
449
    public static boolean isNotBlank(String str);
450
    
451
    // String operations
452
    public static String defaultString(String str);
453
    public static String defaultString(String str, String defaultStr);
454
    public static String trim(String str);
455
    public static String trimToNull(String str);
456
    public static String trimToEmpty(String str);
457
    
458
    // Joining and splitting
459
    public static String join(String[] array, String separator);
460
    public static String join(Iterable<?> iterable, String separator);
461
    public static String[] split(String str, String separatorChars);
462
    
463
    // Conversion utilities
464
    public static String capitalize(String str);
465
    public static String uncapitalize(String str);
466
    public static String camelToSnakeCase(String camelCase);
467
    public static String snakeToCamelCase(String snakeCase);
468
}
469
```
470

471
### MathUtils
472

473
Mathematical utilities and operations.
474

475
```java { .api }
476
public class MathUtils {
477
    // Number utilities
478
    public static int nextPowerOfTwo(int value);
479
    public static long nextPowerOfTwo(long value);
480
    public static boolean isPowerOfTwo(int value);
481
    public static boolean isPowerOfTwo(long value);
482
    
483
    // Min/max operations
484
    public static int min(int a, int b, int c);
485
    public static int max(int a, int b, int c);
486
    public static long min(long a, long b, long c);
487
    public static long max(long a, long b, long c);
488
    
489
    // Clipping and bounds
490
    public static int clip(int value, int min, int max);
491
    public static long clip(long value, long min, long max);
492
    public static double clip(double value, double min, double max);
493
    
494
    // Hash utilities
495
    public static int hash(int value);
496
    public static int hash(long value);
497
    public static int hash(Object obj);
498
    public static int combineHash(int hash1, int hash2);
499
}
500
```
501

502
## Usage Examples
503

504
### High-Performance Collections
505

506
```java
507
import org.apache.fury.collection.FuryObjectMap;
508
import org.apache.fury.collection.IntArray;
509

510
// Use FuryObjectMap for high-performance key-value storage
511
FuryObjectMap<String, User> userMap = new FuryObjectMap<>();
512
userMap.put("user1", new User("Alice"));
513
userMap.put("user2", new User("Bob"));
514

515
// Get performance statistics
516
MapStatistics stats = userMap.getStatistics();
517
System.out.println("Load factor: " + stats.getLoadFactor());
518
System.out.println("Collision rate: " + stats.getCollisionRate());
519

520
// Use IntArray for efficient primitive storage
521
IntArray scores = new IntArray();
522
scores.add(95);
523
scores.add(87);
524
scores.add(92);
525

526
// Convert to standard array when needed
527
int[] scoresArray = scores.toArray();
528
```
529

530
### Specialized Maps
531

532
```java
533
import org.apache.fury.collection.LongMap;
534
import org.apache.fury.collection.ObjectIntMap;
535

536
// Use LongMap for primitive long keys
537
LongMap<String> idToName = new LongMap<>();
538
idToName.put(1001L, "Alice");
539
idToName.put(1002L, "Bob");
540

541
// Use ObjectIntMap for counting scenarios
542
ObjectIntMap<String> wordCounts = new ObjectIntMap<>();
543
wordCounts.put("hello", 5);
544
wordCounts.put("world", 3);
545
wordCounts.increment("hello");  // Now 6
546

547
// Get statistics
548
int totalWords = wordCounts.sum();  // 9
549
int maxCount = wordCounts.max();    // 6
550
```
551

552
### Tuple Usage
553

554
```java
555
import org.apache.fury.collection.Tuple2;
556
import org.apache.fury.collection.Tuple3;
557

558
// Create immutable tuples
559
Tuple2<String, Integer> nameAge = Tuple2.of("Alice", 30);
560
Tuple3<String, Integer, String> nameAgeCity = Tuple3.of("Bob", 25, "NYC");
561

562
// Access elements
563
String name = nameAge.getF0();  // or nameAge._1()
564
Integer age = nameAge.getF1();  // or nameAge._2()
565

566
// Use in collections
567
List<Tuple2<String, Integer>> people = Arrays.asList(
568
    Tuple2.of("Alice", 30),
569
    Tuple2.of("Bob", 25),
570
    Tuple2.of("Charlie", 35)
571
);
572

573
// Use mutable tuples for modification
574
MutableTuple2<String, Integer> mutableTuple = new MutableTuple2<>("Alice", 30);
575
mutableTuple.setF1(31);  // Update age
576
Tuple2<String, Integer> immutable = mutableTuple.toImmutable();
577
```
578

579
### Lazy Collections
580

581
```java
582
import org.apache.fury.collection.LazyMap;
583

584
// Create lazy map with expensive computation
585
LazyMap<String, ExpensiveObject> lazyCache = new LazyMap<>(key -> {
586
    // This computation only happens when the key is accessed
587
    return computeExpensiveObject(key);
588
});
589

590
// Values are computed on-demand
591
ExpensiveObject obj1 = lazyCache.get("key1");  // Computes value
592
ExpensiveObject obj2 = lazyCache.get("key1");  // Returns cached value
593

594
// Check if value is already computed
595
if (!lazyCache.isComputed("key2")) {
596
    // Pre-compute if needed
597
    lazyCache.compute("key2");
598
}
599
```
600

601
### Utility Usage
602

603
```java
604
import org.apache.fury.util.Preconditions;
605
import org.apache.fury.util.StringUtils;
606
import org.apache.fury.util.MathUtils;
607

608
// Preconditions for validation
609
public void processUser(User user) {
610
    Preconditions.checkNotNull(user, "User cannot be null");
611
    Preconditions.checkArgument(user.getAge() >= 0, "Age must be non-negative");
612
    Preconditions.checkState(isInitialized(), "Service not initialized");
613
    
614
    // Process user...
615
}
616

617
// String utilities
618
String input = "  hello world  ";
619
String cleaned = StringUtils.trimToEmpty(input);
620
String[] words = StringUtils.split(cleaned, " ");
621
String joined = StringUtils.join(words, "-");  // "hello-world"
622

623
// Convert case
624
String camel = StringUtils.snakeToCamelCase("user_name");  // "userName"
625
String snake = StringUtils.camelToSnakeCase("userName");  // "user_name"
626

627
// Math utilities
628
int capacity = MathUtils.nextPowerOfTwo(1000);  // 1024
629
int clipped = MathUtils.clip(150, 0, 100);      // 100
630
```
631

632
### Collection Utilities
633

634
```java
635
import org.apache.fury.collection.Collections;
636

637
// Create collections efficiently
638
List<String> names = Collections.ofList("Alice", "Bob", "Charlie");
639
Set<Integer> numbers = Collections.ofSet(1, 2, 3, 4, 5);
640
Map<String, Integer> ageMap = Collections.ofMap("Alice", 30, "Bob", 25);
641

642
// Collection operations
643
List<String> filtered = Collections.filter(names, name -> name.startsWith("A"));
644
List<Integer> lengths = Collections.map(names, String::length);
645
List<String> reversed = Collections.reverse(names);
646

647
// Safe collection operations
648
boolean isEmpty = Collections.isEmpty(names);
649
int size = Collections.size(names);
650
```
651

652
## Performance Considerations
653

654
### Collection Selection
655

656
- **FuryObjectMap**: Best for frequent lookups with object keys
657
- **LongMap/ObjectIntMap**: Use for primitive key/value scenarios
658
- **IntArray**: More efficient than ArrayList<Integer> for primitives
659
- **IdentityMap**: Use when reference equality is needed
660

661
### Memory Optimization
662

663
- **Primitive Collections**: Avoid boxing overhead with primitive-specific collections
664
- **Capacity Planning**: Pre-size collections when final size is known
665
- **Lazy Loading**: Use LazyMap for expensive-to-compute values
666
- **Weak References**: Use MultiKeyWeakMap for cache scenarios
667

668
### Best Practices
669

670
1. **Choose Right Collection**: Match collection type to usage pattern
671
2. **Pre-size Collections**: Set initial capacity when size is predictable
672
3. **Use Primitive Collections**: Avoid boxing for primitive data
673
4. **Monitor Performance**: Use MapStatistics for performance insights
674
5. **Memory Management**: Clear collections when no longer needed