0
# Collection Operations
1

2
Utilities for creating, manipulating, and transforming Java collections with null-safe operations through the CollUtil class.
3

4
## Capabilities
5

6
### Collection Validation
7

8
Check if collections are null or empty with null-safe operations.
9

10
```java { .api }
11
/**
12
 * Check if a collection is empty (null or size == 0)
13
 * @param collection the collection to check
14
 * @return true if the collection is empty or null
15
 */
16
public static <T> boolean isEmpty(Collection<T> collection);
17

18
/**
19
 * Check if a collection is not empty
20
 * @param collection the collection to check
21
 * @return true if the collection is not empty and not null
22
 */
23
public static <T> boolean isNotEmpty(Collection<T> collection);
24

25
/**
26
 * Return empty set if provided set is null, otherwise return original set
27
 * @param set the set to check
28
 * @return original set or empty set if null
29
 */
30
public static <T> Set<T> emptyIfNull(Set<T> set);
31

32
/**
33
 * Return empty list if provided list is null, otherwise return original list
34
 * @param list the list to check
35
 * @return original list or empty list if null
36
 */
37
public static <T> List<T> emptyIfNull(List<T> list);
38
```
39

40
**Usage Examples:**
41

42
```java
43
import cn.hutool.core.collection.CollUtil;
44
import java.util.*;
45

46
// Validation
47
List<String> list1 = null;
48
List<String> list2 = new ArrayList<>();
49
List<String> list3 = Arrays.asList("a", "b", "c");
50

51
boolean isEmpty1 = CollUtil.isEmpty(list1);    // true
52
boolean isEmpty2 = CollUtil.isEmpty(list2);    // true
53
boolean isEmpty3 = CollUtil.isEmpty(list3);    // false
54

55
boolean notEmpty1 = CollUtil.isNotEmpty(list1); // false
56
boolean notEmpty2 = CollUtil.isNotEmpty(list3); // true
57

58
// Safe operations
59
List<String> safe = CollUtil.emptyIfNull(list1); // Returns Collections.emptyList()
60
```
61

62
### Collection Creation
63

64
Create various types of collections with convenient factory methods.
65

66
```java { .api }
67
/**
68
 * Create a new ArrayList with initial values
69
 * @param values initial values for the list
70
 * @return new ArrayList containing the values
71
 */
72
public static <T> List<T> newArrayList(T... values);
73

74
/**
75
 * Create a new LinkedList with initial values
76
 * @param values initial values for the list
77
 * @return new LinkedList containing the values
78
 */
79
public static <T> LinkedList<T> newLinkedList(T... values);
80

81
/**
82
 * Create a new HashSet with initial values
83
 * @param values initial values for the set
84
 * @return new HashSet containing the values
85
 */
86
public static <T> Set<T> newHashSet(T... values);
87

88
/**
89
 * Create a new LinkedHashSet with initial values
90
 * @param values initial values for the set
91
 * @return new LinkedHashSet containing the values
92
 */
93
public static <T> Set<T> newLinkedHashSet(T... values);
94

95
/**
96
 * Create a new concurrent collection
97
 * @param values initial values
98
 * @return new CopyOnWriteArrayList containing the values
99
 */
100
public static <T> CopyOnWriteArrayList<T> newCopyOnWriteArrayList(T... values);
101
```
102

103
**Usage Examples:**
104

105
```java
106
// Create collections with initial values
107
List<String> list = CollUtil.newArrayList("a", "b", "c");
108
Set<Integer> numbers = CollUtil.newHashSet(1, 2, 3, 4, 5);
109
LinkedList<String> linkedList = CollUtil.newLinkedList("first", "second");
110

111
// Thread-safe collections
112
CopyOnWriteArrayList<String> concurrent = CollUtil.newCopyOnWriteArrayList("item1", "item2");
113
```
114

115
### Set Operations
116

117
Perform mathematical set operations like union, intersection, and difference.
118

119
```java { .api }
120
/**
121
 * Union of two collections (preserves duplicates by count)
122
 * @param coll1 first collection
123
 * @param coll2 second collection
124
 * @return union collection as ArrayList
125
 */
126
public static <T> Collection<T> union(Collection<T> coll1, Collection<T> coll2);
127

128
/**
129
 * Intersection of two collections
130
 * @param coll1 first collection
131
 * @param coll2 second collection
132
 * @return intersection collection as ArrayList
133
 */
134
public static <T> Collection<T> intersection(Collection<T> coll1, Collection<T> coll2);
135

136
/**
137
 * Difference of two collections (elements in coll1 but not in coll2)
138
 * @param coll1 first collection
139
 * @param coll2 second collection
140
 * @return difference collection as ArrayList
141
 */
142
public static <T> Collection<T> subtract(Collection<T> coll1, Collection<T> coll2);
143

144
/**
145
 * Symmetric difference (elements in either collection but not in both)
146
 * @param coll1 first collection
147
 * @param coll2 second collection
148
 * @return symmetric difference as ArrayList
149
 */
150
public static <T> Collection<T> disjunction(Collection<T> coll1, Collection<T> coll2);
151
```
152

153
**Usage Examples:**
154

155
```java
156
List<String> list1 = CollUtil.newArrayList("a", "b", "c", "c");
157
List<String> list2 = CollUtil.newArrayList("b", "c", "d");
158

159
// Set operations
160
Collection<String> union = CollUtil.union(list1, list2);         // [a, b, c, c, d]
161
Collection<String> intersection = CollUtil.intersection(list1, list2); // [b, c]
162
Collection<String> difference = CollUtil.subtract(list1, list2);  // [a, c]
163
Collection<String> symmetric = CollUtil.disjunction(list1, list2); // [a, c, d]
164
```
165

166
### Collection Transformation
167

168
Transform collections using mapping functions and filters.
169

170
```java { .api }
171
/**
172
 * Map collection elements to new values
173
 * @param collection source collection
174
 * @param mapper function to transform elements
175
 * @return new list with transformed elements
176
 */
177
public static <T, R> List<R> map(Collection<T> collection, Function<T, R> mapper);
178

179
/**
180
 * Filter collection elements based on predicate
181
 * @param collection source collection
182
 * @param predicate filter condition
183
 * @return new list with filtered elements
184
 */
185
public static <T> List<T> filter(Collection<T> collection, Predicate<T> predicate);
186

187
/**
188
 * Extract field values from collection of objects
189
 * @param collection collection of objects
190
 * @param fieldName field name to extract
191
 * @return list of field values
192
 */
193
public static <T> List<Object> getFieldValues(Collection<T> collection, String fieldName);
194
```
195

196
### Collection Conversion
197

198
Convert between different collection types and to arrays.
199

200
```java { .api }
201
/**
202
 * Convert collection to array
203
 * @param collection source collection
204
 * @param componentType array component type
205
 * @return array containing collection elements
206
 */
207
public static <T> T[] toArray(Collection<T> collection, Class<T> componentType);
208

209
/**
210
 * Convert iterable to list
211
 * @param iterable source iterable
212
 * @return new ArrayList containing iterable elements
213
 */
214
public static <T> List<T> toList(Iterable<T> iterable);
215

216
/**
217
 * Convert array to list
218
 * @param array source array
219
 * @return new ArrayList containing array elements
220
 */
221
public static <T> List<T> toList(T[] array);
222
```
223

224
### Collection Utilities
225

226
Additional utility methods for collection manipulation.
227

228
```java { .api }
229
/**
230
 * Get first element of collection
231
 * @param collection the collection
232
 * @return first element or null if empty
233
 */
234
public static <T> T getFirst(Collection<T> collection);
235

236
/**
237
 * Get last element of collection
238
 * @param collection the collection
239
 * @return last element or null if empty
240
 */
241
public static <T> T getLast(Collection<T> collection);
242

243
/**
244
 * Reverse the order of elements in a list
245
 * @param list the list to reverse
246
 * @return the same list with reversed order
247
 */
248
public static <T> List<T> reverse(List<T> list);
249

250
/**
251
 * Sort collection using natural ordering
252
 * @param collection collection to sort
253
 * @return new sorted list
254
 */
255
public static <T extends Comparable<T>> List<T> sort(Collection<T> collection);
256

257
/**
258
 * Sort collection using custom comparator
259
 * @param collection collection to sort
260
 * @param comparator comparator for sorting
261
 * @return new sorted list
262
 */
263
public static <T> List<T> sort(Collection<T> collection, Comparator<T> comparator);
264
```
265

266
**Usage Examples:**
267

268
```java
269
List<String> names = CollUtil.newArrayList("Alice", "Bob", "Charlie");
270

271
// Collection utilities
272
String first = CollUtil.getFirst(names);     // "Alice"
273
String last = CollUtil.getLast(names);       // "Charlie"
274

275
// Transformation
276
List<Integer> lengths = CollUtil.map(names, String::length); // [5, 3, 7]
277
List<String> filtered = CollUtil.filter(names, name -> name.length() > 3); // ["Alice", "Charlie"]
278

279
// Sorting
280
List<String> sorted = CollUtil.sort(names); // Natural alphabetical order
281
List<String> reversed = CollUtil.reverse(CollUtil.newArrayList(names)); // ["Charlie", "Bob", "Alice"]
282

283
// Conversion
284
String[] array = CollUtil.toArray(names, String.class);
285
List<String> backToList = CollUtil.toList(array);
286
```
287

288
## Specialized Collection Classes
289

290
CollUtil also provides access to specialized collection implementations:
291

292
```java { .api }
293
// Queue implementations
294
ArrayBlockingQueue<T> newArrayBlockingQueue(int capacity);
295
LinkedBlockingDeque<T> newLinkedBlockingDeque();
296

297
// Thread-safe collections
298
CopyOnWriteArrayList<T> newCopyOnWriteArrayList(T... values);
299
```
300

301
## Integration with Iterator Utilities
302

303
CollUtil works closely with IterUtil for iterator-based operations. Many operations that work with iterators are provided in IterUtil rather than CollUtil to avoid duplication.