imtoken钱包中国官方网站|collectionutils

java代码之美（12）---CollectionUtils工具类 - 雨点的名字 - 博客园

java代码之美（12）---CollectionUtils工具类 - 雨点的名字 - 博客园

会员

周边

新闻

博问

AI培训

云市场

所有博客

当前博客

我的博客

我的园子

账号设置

简洁模式 ...

退出登录

注册

登录

雨点的名字

公众号: 后端元宇宙

首页

新随笔

管理

java代码之美（12）---CollectionUtils工具类

CollectionUtils工具类

这篇讲的CollectionUtils工具类是在apache下的, 而不是springframework下的CollectionUtils。

个人觉得CollectionUtils在真实项目中,可以使你的代码更加简洁和安全。

所以需要倒入相关jar包,目前从maven找到最新jar包如下:

org.apache.commons

commons-collections4

4.3

一、API常用方法

/**

* 1、除非元素为null，否则向集合添加元素

*/

CollectionUtils.addIgnoreNull(personList,null);

/**

* 2、将两个已排序的集合a和b合并为一个已排序的列表，以便保留元素的自然顺序

*/

CollectionUtils.collate(Iterable a, Iterable b)

/**

* 3、将两个已排序的集合a和b合并到一个已排序的列表中，以便保留根据Comparator c的元素顺序。

*/

CollectionUtils.collate(Iterable a, Iterable b, Comparator c)

/**

* 4、返回该个集合中是否含有至少有一个元素

*/

CollectionUtils.containsAny(Collection coll1, T... coll2)

/**

* 5、如果参数是null，则返回不可变的空集合，否则返回参数本身。（很实用 ,最终返回List EMPTY_LIST = new EmptyList<>()）

*/

CollectionUtils.emptyIfNull(Collection collection)

/**

* 6、空安全检查指定的集合是否为空

*/

CollectionUtils.isEmpty(Collection coll)

/**

* 7、 空安全检查指定的集合是否为空。

*/

CollectionUtils.isNotEmpty(Collection coll)

/**

* 8、反转给定数组的顺序。

*/

CollectionUtils.reverseArray(Object[] array);

/**

* 9、差集

*/

CollectionUtils.subtract(Iterable a, Iterable b)

/**

* 10、并集

*/

CollectionUtils.union(Iterable a, Iterable b)

/**

* 11、交集

*/

CollectionUtils.intersection(Collection a, Collection b)

/**

*12、 交集的补集（析取）

*/

CollectionUtils.disjunction(Collection a, Collection b)

二、非对象集合交、并、差处理

对于集合取交集、并集的处理其实有很多种方式,这里就介绍3种

第一种 是CollectionUtils工具类

第二种 是List自带方法

第三种 是JDK1.8 stream 新特性

1、CollectionUtils工具类

下面对于基本数据(包扩String)类型中的集合进行demo示例。

public static void main(String[] args) {

String[] arrayA = new String[] { "1", "2", "3", "4"};

String[] arrayB = new String[] { "3", "4", "5", "6" };

List listA = Arrays.asList(arrayA);

List listB = Arrays.asList(arrayB);

//1、并集 union

System.out.println(CollectionUtils.union(listA, listB));

//输出: [1, 2, 3, 4, 5, 6]

//2、交集 intersection

System.out.println(CollectionUtils.intersection(listA, listB));

//输出:[3, 4]

//3、交集的补集（析取）disjunction

System.out.println(CollectionUtils.disjunction(listA, listB));

//输出:[1, 2, 5, 6]

//4、差集（扣除）

System.out.println(CollectionUtils.subtract(listA, listB));

//输出:[1, 2]

}

2、List自带方法

public static void main(String[] args) {

String[] arrayA = new String[] { "1", "2", "3", "4"};

String[] arrayB = new String[] { "3", "4", "5", "6" };

List listA = Arrays.asList(arrayA);

List listB = Arrays.asList(arrayB);

//1、交集

List jiaoList = new ArrayList<>(listA);

jiaoList.retainAll(listB);

System.out.println(jiaoList);

//输出:[3, 4]

//2、差集

List chaList = new ArrayList<>(listA);

chaList.removeAll(listB);

System.out.println(chaList);

//输出:[1, 2]

//3、并集 (先做差集再做添加所有）

List bingList = new ArrayList<>(listA);

bingList.removeAll(listB); // bingList为 [1, 2]

bingList.addAll(listB); //添加[3,4,5,6]

System.out.println(bingList);

//输出:[1, 2, 3, 4, 5, 6]

}

注意 : intersection和retainAll的差别

要注意的是它们的返回类型是不一样的,intersection返回的是一个新的List集合，而retainAll返回是Bollean类型那就说明retainAll方法是对原有集合进行处理再返回原有集合,会改变原有集合中的内容。

个人观点：1、从性能角度来考虑的话,List自带会高点,因为它不用再创建新的集合。2、需要注意的是：因为retainAll因为会改变原有集合,所以该集合需要多次使用就不适合用retainAll。

注意 : Arrays.asList将数组转集合不能进行add和remove操作。

原因：调用Arrays.asList()生产的List的add、remove方法时报异常，这是由Arrays.asList() 返回的市Arrays的内部类ArrayList， 而不是java.util.ArrayList。Arrays的内部类ArrayList和java.util.ArrayList都是继承AbstractList，remove、add等方法AbstractList中是默认throw UnsupportedOperationException而且不作任何操作。java.util.ArrayList重新了这些方法而Arrays的内部类ArrayList没有重新，所以会抛出异常。

所以正确做法如下

String[] array = {"1","2","3","4","5"};

List list = Arrays.asList(array);

List arrList = new ArrayList(list);

arrList.add("6");

3、JDK1.8 stream 新特性

public static void main(String[] args) {

String[] arrayA = new String[] { "1", "2", "3", "4"};

String[] arrayB = new String[] { "3", "4", "5", "6" };

List listA = Arrays.asList(arrayA);

List listB = Arrays.asList(arrayB);

// 交集

List intersection = listA.stream().filter(item -> listB.contains(item)).collect(toList());

System.out.println(intersection);

//输出:[3, 4]

// 差集 (list1 - list2)

List reduceList = listA.stream().filter(item -> !listB.contains(item)).collect(toList());

System.out.println(reduceList);

//输出:[1, 2]

// 并集 （新建集合:1、是因为不影响原始集合。2、Arrays.asList不能add和remove操作。

List listAll = listA.parallelStream().collect(toList());

List listAll2 = listB.parallelStream().collect(toList());

listAll.addAll(listAll2);

System.out.println(listAll);

//输出:[1, 2, 3, 4, 3, 4, 5, 6]

// 去重并集

List list =new ArrayList<>(listA);

list.addAll(listB);

List listAllDistinct = list.stream().distinct().collect(toList());

System.out.println(listAllDistinct);

//输出:[1, 2, 3, 4, 5, 6]

}

总结 ： 这三种我还是最喜欢第一种方式，因为第二种还需要确定该集合是否被多次调用。第三种可读性不高。

三、对象集合交、并、差处理

因为对象的equels比较是比较两个对象的内存地址，所以除非是同一对象，否则equel返回永远是false。

但我们实际开发中 在我们的业务系统中判断对象时有时候需要的不是一种严格意义上的相等，而是一种业务上的对象相等。在这种情况下，原生的equals方法就不能满足我们的需求了，所以这个时候我们需要重写equals方法。

说明 :String为什么可以使用equels方法为什么只要字符串相等就为true,那是因为String类重写了equal和hashCode方法，比较的是值。

1、Person对象

public class Person {

private String name;

private Integer age;

public Person(String name, Integer age) {

this.name = name;

this.age = age;

}

/**

* 为什么重写equals方法一定要重写hashCode方法下面也会讲

*/

@Override

public int hashCode() {

String result = name + age;

return result.hashCode();

}

/**

* 重写 equals 方法 根据name和age都相同那么对象就默认相同

*/

@Override

public boolean equals(Object obj) {

Person u = (Person) obj;

return this.getName().equals(u.getName()) && (this.age.equals(u.getAge()));

}

/**

* 重写 toString 方法

*/

@Override

public String toString() {

return "Person{" +

"name='" + name + '\'' +

", age=" + age +

'}';

}

}

2、测试

这里根据name和age都相同那么就默认相同对象。

public static void main(String[] args) {

List personList = Lists.newArrayList();

Person person1 = new Person("小小",3);

Person person2 = new Person("中中",4);

personList.add(person1);

personList.add(person2);

List person1List = Lists.newArrayList();

Person person3 = new Person("中中",4);

Person person4 = new Person("大大",5);

person1List.add(person3);

person1List.add(person4);

/**

* 1、差集

*/

System.out.println(CollectionUtils.subtract(personList, person1List));

//输出:[Person{name='小小', age=3}]

/**

* 2、并集

*/

System.out.println(CollectionUtils.union(personList, person1List));

//输出:[Person{name='小小', age=3}, Person{name='中中', age=4}, Person{name='大大', age=5}]

/**

* 3、交集

*/

System.out.println(CollectionUtils.intersection(personList, person1List));

//输出:[Person{name='中中', age=4}]

/**

* 4、交集的补集（析取）

*/

System.out.println(CollectionUtils.disjunction(personList, person1List));

//输出:[Person{name='小小', age=3}, Person{name='大大', age=5}]

}

其它两种方式就不在测了，因为都一样。

四、为什么重写equels方法一定要重写hashCode方法

1、源码

其实上面的Person类我可以只重写equels方法而不写hashCode方法,一样能达到上面的效果。但为什么还是建议写上呢？官方的说法是:对象的equals方法被重写，那么对象的hashCode()也尽量重写。

重写equals()方法就必须重写hashCode()方法的原因，从源头Object类讲起就更好理解了。

先来看Object关于hashCode()和equals()的源码：

public native int hashCode();

public boolean equals(Object obj) {

return (this == obj);

}

光从代码中我们可以知道，hashCode()方法是一个本地native方法，返回的是对象引用中存储的对象的内存地址。而equals方法是利用==来比较的也是对象的内存地址。从上边我们可以看出，hashCode方法和equals方法是一致的。还有最关键的一点，我们来看Object类中关于hashCode()方法的注释：

1.在 Java 应用程序执行期间，在对同一对象多次调用 hashCode 方法时，必须一致地返回相同的整数，前提是将对象进行 equals 比较时所用的信息没有被修改。

2.如果根据 equals(Object) 方法，两个对象是相等的，那么对这两个对象中的每个对象调用 hashCode 方法都必须生成相同的整数结果。

3.如果根据 equals(java.lang.Object) 方法，两个对象不相等，那么对这两个对象中的任一对象上调用 hashCode 方法不 要求一定生成不同的整数结果。

但是，程序员应该意识到，为不相等的对象生成不同整数结果可以提高哈希表的性能。

整理 : hashCode()和equals()保持一致，如果equals方法返回true，那么两个对象的hasCode()返回值必须一样。如果equals方法返回false，hashcode可以不一样，但是这样不利于哈希表的性能，一般我们也不要这样做。

假设两个对象，重写了其equals方法，其相等条件是某属性相等，就返回true。如果不重写hashcode方法，其返回的依然是两个对象的内存地址值，必然不相等。这就出现了equals方法相等，但是hashcode不相等的情况。这不符合hashcode的规则。

2、HashSet和Map集合类型

重写equals()方法就必须重写hashCode()方法主要是针对HashSet和Map集合类型,而对于List集合倒没什么影响。

原因： 在向HashSet集合中存入一个元素时，HashSet会调用该对象（存入对象）的hashCode()方法来得到该对象的hashCode()值，然后根据该hashCode值决定该对象在HashSet中存储的位置。简单的说：HashSet集合判断两个元素相等的标准是：两个对象通过equals()方法比较相等，并且两个对象的HashCode()方法返回值也相等。如果两个元素通过equals()方法比较返回true，但是它们的hashCode()方法返回值不同，HashSet会把它们存储在不同的位置，依然可以添加成功。

这就是问题所在：就是如果你只重写equals()方法，而不重写hashCode(),如果equals()为true,而它们的hashCode()方法返回值肯定不一样，因为它们都不是同一对象所以内存地址肯定不一样，所以它还是添加成功了，那么其实你写的equals()方法根本没啥软用。

3、代码示例

1、People类

重写equals方法,但并没有hashCode方法。

public class People {

private String name;

private Integer age;

public People(String name, Integer age) {

this.name = name;

this.age = age;

}

/**

* 重写 equals 方法

*/

@Override

public boolean equals(Object obj) {

People u = (People) obj;

return this.getName().equals(u.getName()) && (this.age.equals(u.getAge()));

}

/**

* 重写 toString 方法

*/

@Override

public String toString() {

return "People{" +

"name='" + name + '\'' +

", age=" + age +

'}';

}

}

2、实现类

public static void main(String[] args) {

HashSet hashSet = Sets.newHashSet();

People people1 = new People("小小",3);

People people2 = new People("中中",4);

People people3 = new People("中中",4);

People people4 = new People("大大",5);

hashSet.add(people1);

hashSet.add(people2);

hashSet.add(people3);

hashSet.add(people4);

System.out.println(hashSet);

//输出:[People{name='小小', age=3}, People{name='中中', age=4}, People{name='大大', age=5}, People{name='中中', age=4}]

}

很明显,我重写了equals方法,那么people2和people3的equals应该相同，所以不能放入HashSet,但它们的hashCode()方法返回不同，所以导致同样能放入HashSet。

重点：对于Set集合必须要同时重写这两个方法，要不然Set的特性就被破坏了。

只要自己变优秀了，其他的事情才会跟着好起来（少将8）

posted on

2019-04-28 21:57 

雨点的名字 

阅读(40737) 

评论(4) 

编辑 

收藏 

举报

会员力量，点亮园子希望

刷新页面返回顶部

Powered by: 博客园

Copyright © 2024 雨点的名字

Powered by .NET 8.0 on Kubernetes

CollectionUtils (Apache Commons Collections 4.4 API)

CollectionUtils (Apache Commons Collections 4.4 API)

JavaScript is disabled on your browser.

Skip navigation links

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Prev Class

Next Class

Frames

No Frames

All Classes

Summary: 

Nested | 

Field | 

Constr | 

Method

Detail: 

Field | 

Constr | 

Method

org.apache.commons.collections4

Class CollectionUtils

java.lang.Object

org.apache.commons.collections4.CollectionUtils

public class CollectionUtils

extends Object

Provides utility methods and decorators for Collection instances.

Various utility methods might put the input objects into a Set/Map/Bag. In case

the input objects override Object.equals(Object), it is mandatory that

the general contract of the Object.hashCode() method is maintained.

NOTE: From 4.0, method parameters will take Iterable objects when possible.

Since:

1.0

Field Summary

Fields 

Modifier and Type

Field and Description

static Collection

EMPTY_COLLECTION

An empty unmodifiable collection.

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods 

Modifier and Type

Method and Description

static  boolean

addAll(Collection collection,

C... elements)

Adds all elements in the array to the given collection.

static  boolean

addAll(Collection collection,

Enumeration enumeration)

Adds all elements in the enumeration to the given collection.

static  boolean

addAll(Collection collection,

Iterable iterable)

Adds all elements in the Iterable to the given collection.

static  boolean

addAll(Collection collection,

Iterator iterator)

Adds all elements in the iteration to the given collection.

static  boolean

addIgnoreNull(Collection collection,

T object)

Adds an element to the collection unless the element is null.

static  int

cardinality(O obj,

Iterable coll)

Deprecated. 

since 4.1, use IterableUtils.frequency(Iterable, Object) instead.

Be aware that the order of parameters has changed.

static >List

collate(Iterable a,

Iterable b)

Merges two sorted Collections, a and b, into a single, sorted List

such that the natural ordering of the elements is retained.

static >List

collate(Iterable a,

Iterable b,

boolean includeDuplicates)

Merges two sorted Collections, a and b, into a single, sorted List

such that the natural ordering of the elements is retained.

static  List

collate(Iterable a,

Iterable b,

Comparator c)

Merges two sorted Collections, a and b, into a single, sorted List

such that the ordering of the elements according to Comparator c is retained.

static  List

collate(Iterable a,

Iterable b,

Comparator c,

boolean includeDuplicates)

Merges two sorted Collections, a and b, into a single, sorted List

such that the ordering of the elements according to Comparator c is retained.

static >R

collect(Iterable inputCollection,

Transformer transformer,

R outputCollection)

Transforms all elements from input collection with the given transformer

and adds them to the output collection.

static  Collection

collect(Iterable inputCollection,

Transformer transformer)

Returns a new Collection containing all elements of the input collection

transformed by the given transformer.

static >R

collect(Iterator inputIterator,

Transformer transformer,

R outputCollection)

Transforms all elements from the input iterator with the given transformer

and adds them to the output collection.

static  Collection

collect(Iterator inputIterator,

Transformer transformer)

Transforms all elements from the input iterator with the given transformer

and adds them to the output collection.

static boolean

containsAll(Collection coll1,

Collection coll2)

Returns true iff all elements of coll2 are also contained

in coll1.

static boolean

containsAny(Collection coll1,

Collection coll2)

Returns true iff at least one element is in both collections.

static  boolean

containsAny(Collection coll1,

T... coll2)

Returns true iff at least one element is in both collections.

static  int

countMatches(Iterable input,

Predicate predicate)

Deprecated. 

since 4.1, use IterableUtils.countMatches(Iterable, Predicate) instead

static  Collection

disjunction(Iterable a,

Iterable b)

Returns a Collection containing the exclusive disjunction

(symmetric difference) of the given Iterables.

static  Collection

emptyCollection()

Returns the immutable EMPTY_COLLECTION with generic type safety.

static  Collection

emptyIfNull(Collection collection)

Returns an immutable empty collection if the argument is null,

or the argument itself otherwise.

static  boolean

exists(Iterable input,

Predicate predicate)

Deprecated. 

since 4.1, use IterableUtils.matchesAny(Iterable, Predicate) instead

static  E

extractSingleton(Collection collection)

Extract the lone element of the specified Collection.

static  boolean

filter(Iterable collection,

Predicate predicate)

Filter the collection by applying a Predicate to each element.

static  boolean

filterInverse(Iterable collection,

Predicate predicate)

Filter the collection by applying a Predicate to each element.

static  T

find(Iterable collection,

Predicate predicate)

Deprecated. 

since 4.1, use IterableUtils.find(Iterable, Predicate) instead

static >T

forAllButLastDo(Iterable collection,

C closure)

Deprecated. 

since 4.1, use IterableUtils.forEachButLast(Iterable, Closure) instead

static >T

forAllButLastDo(Iterator iterator,

C closure)

Deprecated. 

since 4.1, use IteratorUtils.forEachButLast(Iterator, Closure) instead

static >C

forAllDo(Iterable collection,

C closure)

Deprecated. 

since 4.1, use IterableUtils.forEach(Iterable, Closure) instead

static >C

forAllDo(Iterator iterator,

C closure)

Deprecated. 

since 4.1, use IteratorUtils.forEach(Iterator, Closure) instead

static  T

get(Iterable iterable,

int index)

Deprecated. 

since 4.1, use IterableUtils.get(Iterable, int) instead

static  T

get(Iterator iterator,

int index)

Deprecated. 

since 4.1, use IteratorUtils.get(Iterator, int) instead

static  Map.Entry

get(Map map,

int index)

Returns the index-th Map.Entry in the map's entrySet,

throwing IndexOutOfBoundsException if there is no such element.

static Object

get(Object object,

int index)

Returns the index-th value in object, throwing

IndexOutOfBoundsException if there is no such element or

IllegalArgumentException if object is not an

instance of one of the supported types.

static  Map

getCardinalityMap(Iterable coll)

Returns a Map mapping each unique element in the given

Collection to an Integer representing the number

of occurrences of that element in the Collection.

static  Collection

intersection(Iterable a,

Iterable b)

Returns a Collection containing the intersection of the given

Iterables.

static boolean

isEmpty(Collection coll)

Null-safe check if the specified collection is empty.

static boolean

isEqualCollection(Collection a,

Collection b)

Returns true iff the given Collections contain

exactly the same elements with exactly the same cardinalities.

static  boolean

isEqualCollection(Collection a,

Collection b,

Equator equator)

Returns true iff the given Collections contain

exactly the same elements with exactly the same cardinalities.

static boolean

isFull(Collection coll)

Returns true if no more elements can be added to the Collection.

static boolean

isNotEmpty(Collection coll)

Null-safe check if the specified collection is not empty.

static boolean

isProperSubCollection(Collection a,

Collection b)

Returns true iff a is a proper sub-collection of b,

that is, iff the cardinality of e in a is less

than or equal to the cardinality of e in b,

for each element e in a, and there is at least one

element f such that the cardinality of f in b

is strictly greater than the cardinality of f in a.

static boolean

isSubCollection(Collection a,

Collection b)

Returns true iff a is a sub-collection of b,

that is, iff the cardinality of e in a is less than or

equal to the cardinality of e in b, for each element e

in a.

static  boolean

matchesAll(Iterable input,

Predicate predicate)

Deprecated. 

since 4.1, use IterableUtils.matchesAll(Iterable, Predicate) instead

static int

maxSize(Collection coll)

Get the maximum number of elements that the Collection can contain.

static  Collection>

permutations(Collection collection)

Returns a Collection of all the permutations of the input collection.

static  Collection

predicatedCollection(Collection collection,

Predicate predicate)

Returns a predicated (validating) collection backed by the given collection.

static  Collection

removeAll(Collection collection,

Collection remove)

Removes the elements in remove from collection.

static  Collection

removeAll(Iterable collection,

Iterable remove,

Equator equator)

Removes all elements in remove from collection.

static  Collection

retainAll(Collection collection,

Collection retain)

Returns a collection containing all the elements in collection

that are also in retain.

static  Collection

retainAll(Iterable collection,

Iterable retain,

Equator equator)

Returns a collection containing all the elements in

collection that are also in retain.

static void

reverseArray(Object[] array)

Reverses the order of the given array.

static  Collection

select(Iterable inputCollection,

Predicate predicate)

Selects all elements from input collection which match the given

predicate into an output collection.

static >R

select(Iterable inputCollection,

Predicate predicate,

R outputCollection)

Selects all elements from input collection which match the given

predicate and adds them to outputCollection.

static >R

select(Iterable inputCollection,

Predicate predicate,

R outputCollection,

R rejectedCollection)

Selects all elements from inputCollection into an output and rejected collection,

based on the evaluation of the given predicate.

static  Collection

selectRejected(Iterable inputCollection,

Predicate predicate)

Selects all elements from inputCollection which don't match the given

predicate into an output collection.

static >R

selectRejected(Iterable inputCollection,

Predicate predicate,

R outputCollection)

Selects all elements from inputCollection which don't match the given

predicate and adds them to outputCollection.

static int

size(Object object)

Gets the size of the collection/iterator specified.

static boolean

sizeIsEmpty(Object object)

Checks if the specified collection/array/iterator is empty.

static  Collection

subtract(Iterable a,

Iterable b)

Returns a new Collection containing a - b.

static  Collection

subtract(Iterable a,

Iterable b,

Predicate p)

Returns a new Collection containing a minus a subset of

b.

static  Collection

synchronizedCollection(Collection collection)

Deprecated. 

since 4.1, use Collections.synchronizedCollection(Collection) instead

static  void

transform(Collection collection,

Transformer transformer)

Transform the collection by applying a Transformer to each element.

static  Collection

transformingCollection(Collection collection,

Transformer transformer)

Returns a transformed bag backed by the given collection.

static  Collection

union(Iterable a,

Iterable b)

Returns a Collection containing the union of the given

Iterables.

static  Collection

unmodifiableCollection(Collection collection)

Deprecated. 

since 4.1, use Collections.unmodifiableCollection(Collection) instead

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_COLLECTION

public static final Collection EMPTY_COLLECTION

An empty unmodifiable collection.

The JDK provides empty Set and List implementations which could be used for

this purpose. However they could be cast to Set or List which might be

undesirable. This implementation only implements Collection.

Method Detail

emptyCollection

public static  Collection emptyCollection()

Returns the immutable EMPTY_COLLECTION with generic type safety.

Type Parameters:

T - the element type

Returns:

immutable empty collection

Since:

4.0

See Also:

EMPTY_COLLECTION

emptyIfNull

public static  Collection emptyIfNull(Collection collection)

Returns an immutable empty collection if the argument is null,

or the argument itself otherwise.

Type Parameters:

T - the element type

Parameters:

collection - the collection, possibly null

Returns:

an empty collection if the argument is null

union

public static  Collection union(Iterable a,

Iterable b)

Returns a Collection containing the union of the given

Iterables.

The cardinality of each element in the returned Collection will

be equal to the maximum of the cardinality of that element in the two

given Iterables.

Type Parameters:

O - the generic type that is able to represent the types contained

in both input collections.

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

Returns:

the union of the two collections

See Also:

Collection.addAll(java.util.Collection)

intersection

public static  Collection intersection(Iterable a,

Iterable b)

Returns a Collection containing the intersection of the given

Iterables.

The cardinality of each element in the returned Collection will

be equal to the minimum of the cardinality of that element in the two

given Iterables.

Type Parameters:

O - the generic type that is able to represent the types contained

in both input collections.

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

Returns:

the intersection of the two collections

See Also:

Collection.retainAll(java.util.Collection),

containsAny(java.util.Collection, T...)

disjunction

public static  Collection disjunction(Iterable a,

Iterable b)

Returns a Collection containing the exclusive disjunction

(symmetric difference) of the given Iterables.

The cardinality of each element e in the returned

Collection will be equal to

max(cardinality(e,a),cardinality(e,b)) - min(cardinality(e,a),

cardinality(e,b)).

This is equivalent to

{@link #subtract subtract}({@link #union union(a,b)},{@link #intersection intersection(a,b)})

or

{@link #union union}({@link #subtract subtract(a,b)},{@link #subtract subtract(b,a)}).

Type Parameters:

O - the generic type that is able to represent the types contained

in both input collections.

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

Returns:

the symmetric difference of the two collections

subtract

public static  Collection subtract(Iterable a,

Iterable b)

Returns a new Collection containing a - b.

The cardinality of each element e in the returned Collection

will be the cardinality of e in a minus the cardinality

of e in b, or zero, whichever is greater.

Type Parameters:

O - the generic type that is able to represent the types contained

in both input collections.

Parameters:

a - the collection to subtract from, must not be null

b - the collection to subtract, must not be null

Returns:

a new collection with the results

See Also:

Collection.removeAll(java.util.Collection)

subtract

public static  Collection subtract(Iterable a,

Iterable b,

Predicate p)

Returns a new Collection containing a minus a subset of

b. Only the elements of b that satisfy the predicate

condition, p are subtracted from a.

The cardinality of each element e in the returned Collection

that satisfies the predicate condition will be the cardinality of e in a

minus the cardinality of e in b, or zero, whichever is greater.

The cardinality of each element e in the returned Collection that does not

satisfy the predicate condition will be equal to the cardinality of e in a.

Type Parameters:

O - the generic type that is able to represent the types contained

in both input collections.

Parameters:

a - the collection to subtract from, must not be null

b - the collection to subtract, must not be null

p - the condition used to determine which elements of b are

subtracted.

Returns:

a new collection with the results

Since:

4.0

See Also:

Collection.removeAll(java.util.Collection)

containsAll

public static boolean containsAll(Collection coll1,

Collection coll2)

Returns true iff all elements of coll2 are also contained

in coll1. The cardinality of values in coll2 is not taken into account,

which is the same behavior as Collection.containsAll(Collection).

In other words, this method returns true iff the

intersection(java.lang.Iterable, java.lang.Iterable) of coll1 and coll2 has the same cardinality as

the set of unique values from coll2. In case coll2 is empty, true

will be returned.

This method is intended as a replacement for Collection.containsAll(Collection)

with a guaranteed runtime complexity of O(n + m). Depending on the type of

Collection provided, this method will be much faster than calling

Collection.containsAll(Collection) instead, though this will come at the

cost of an additional space complexity O(n).

Parameters:

coll1 - the first collection, must not be null

coll2 - the second collection, must not be null

Returns:

true iff the intersection of the collections has the same cardinality

as the set of unique elements from the second collection

Since:

4.0

containsAny

public static  boolean containsAny(Collection coll1,

T... coll2)

Returns true iff at least one element is in both collections.

In other words, this method returns true iff the

intersection(java.lang.Iterable, java.lang.Iterable) of coll1 and coll2 is not empty.

Type Parameters:

T - the type of object to lookup in coll1.

Parameters:

coll1 - the first collection, must not be null

coll2 - the second collection, must not be null

Returns:

true iff the intersection of the collections is non-empty

Since:

4.2

See Also:

intersection(java.lang.Iterable, java.lang.Iterable)

containsAny

public static boolean containsAny(Collection coll1,

Collection coll2)

Returns true iff at least one element is in both collections.

In other words, this method returns true iff the

intersection(java.lang.Iterable, java.lang.Iterable) of coll1 and coll2 is not empty.

Parameters:

coll1 - the first collection, must not be null

coll2 - the second collection, must not be null

Returns:

true iff the intersection of the collections is non-empty

Since:

2.1

See Also:

intersection(java.lang.Iterable, java.lang.Iterable)

getCardinalityMap

public static  Map getCardinalityMap(Iterable coll)

Returns a Map mapping each unique element in the given

Collection to an Integer representing the number

of occurrences of that element in the Collection.

Only those elements present in the collection will appear as

keys in the map.

Type Parameters:

O - the type of object in the returned Map. This is a super type of .

Parameters:

coll - the collection to get the cardinality map for, must not be null

Returns:

the populated cardinality map

isSubCollection

public static boolean isSubCollection(Collection a,

Collection b)

Returns true iff a is a sub-collection of b,

that is, iff the cardinality of e in a is less than or

equal to the cardinality of e in b, for each element e

in a.

Parameters:

a - the first (sub?) collection, must not be null

b - the second (super?) collection, must not be null

Returns:

true iff a is a sub-collection of b

See Also:

isProperSubCollection(java.util.Collection, java.util.Collection),

Collection.containsAll(java.util.Collection)

isProperSubCollection

public static boolean isProperSubCollection(Collection a,

Collection b)

Returns true iff a is a proper sub-collection of b,

that is, iff the cardinality of e in a is less

than or equal to the cardinality of e in b,

for each element e in a, and there is at least one

element f such that the cardinality of f in b

is strictly greater than the cardinality of f in a.

The implementation assumes

a.size() and b.size() represent the

total cardinality of a and b, resp.

a.size() < Integer.MAXVALUE

Parameters:

a - the first (sub?) collection, must not be null

b - the second (super?) collection, must not be null

Returns:

true iff a is a proper sub-collection of b

See Also:

isSubCollection(java.util.Collection, java.util.Collection),

Collection.containsAll(java.util.Collection)

isEqualCollection

public static boolean isEqualCollection(Collection a,

Collection b)

Returns true iff the given Collections contain

exactly the same elements with exactly the same cardinalities.

That is, iff the cardinality of e in a is

equal to the cardinality of e in b,

for each element e in a or b.

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

Returns:

true iff the collections contain the same elements with the same cardinalities.

isEqualCollection

public static  boolean isEqualCollection(Collection a,

Collection b,

Equator equator)

Returns true iff the given Collections contain

exactly the same elements with exactly the same cardinalities.

That is, iff the cardinality of e in a is

equal to the cardinality of e in b,

for each element e in a or b.

Note: from version 4.1 onwards this method requires the input

collections and equator to be of compatible type (using bounded wildcards).

Providing incompatible arguments (e.g. by casting to their rawtypes)

will result in a ClassCastException thrown at runtime.

Type Parameters:

E - the element type

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

equator - the Equator used for testing equality

Returns:

true iff the collections contain the same elements with the same cardinalities.

Throws:

NullPointerException - if the equator is null

Since:

4.0

cardinality

@Deprecated

public static  int cardinality(O obj,

Iterable coll)

Deprecated. since 4.1, use IterableUtils.frequency(Iterable, Object) instead.

Be aware that the order of parameters has changed.

Returns the number of occurrences of obj in coll.

Type Parameters:

O - the type of object that the Iterable may contain.

Parameters:

obj - the object to find the cardinality of

coll - the Iterable to search

Returns:

the number of occurrences of obj in coll

Throws:

NullPointerException - if coll is null

find

@Deprecated

public static  T find(Iterable collection,

Predicate predicate)

Deprecated. since 4.1, use IterableUtils.find(Iterable, Predicate) instead

Finds the first element in the given collection which matches the given predicate.

If the input collection or predicate is null, or no element of the collection

matches the predicate, null is returned.

Type Parameters:

T - the type of object the Iterable contains

Parameters:

collection - the collection to search, may be null

predicate - the predicate to use, may be null

Returns:

the first element of the collection which matches the predicate or null if none could be found

forAllDo

@Deprecated

public static > C forAllDo(Iterable collection,

C closure)

Deprecated. since 4.1, use IterableUtils.forEach(Iterable, Closure) instead

Executes the given closure on each element in the collection.

If the input collection or closure is null, there is no change made.

Type Parameters:

T - the type of object the Iterable contains

C - the closure type

Parameters:

collection - the collection to get the input from, may be null

closure - the closure to perform, may be null

Returns:

closure

forAllDo

@Deprecated

public static > C forAllDo(Iterator iterator,

C closure)

Deprecated. since 4.1, use IteratorUtils.forEach(Iterator, Closure) instead

Executes the given closure on each element in the collection.

If the input collection or closure is null, there is no change made.

Type Parameters:

T - the type of object the Iterator contains

C - the closure type

Parameters:

iterator - the iterator to get the input from, may be null

closure - the closure to perform, may be null

Returns:

closure

Since:

4.0

forAllButLastDo

@Deprecated

public static > T forAllButLastDo(Iterable collection,

C closure)

Deprecated. since 4.1, use IterableUtils.forEachButLast(Iterable, Closure) instead

Executes the given closure on each but the last element in the collection.

If the input collection or closure is null, there is no change made.

Type Parameters:

T - the type of object the Iterable contains

C - the closure type

Parameters:

collection - the collection to get the input from, may be null

closure - the closure to perform, may be null

Returns:

the last element in the collection, or null if either collection or closure is null

Since:

4.0

forAllButLastDo

@Deprecated

public static > T forAllButLastDo(Iterator iterator,

C closure)

Deprecated. since 4.1, use IteratorUtils.forEachButLast(Iterator, Closure) instead

Executes the given closure on each but the last element in the collection.

If the input collection or closure is null, there is no change made.

Type Parameters:

T - the type of object the Collection contains

C - the closure type

Parameters:

iterator - the iterator to get the input from, may be null

closure - the closure to perform, may be null

Returns:

the last element in the collection, or null if either iterator or closure is null

Since:

4.0

filter

public static  boolean filter(Iterable collection,

Predicate predicate)

Filter the collection by applying a Predicate to each element. If the

predicate returns false, remove the element.

If the input collection or predicate is null, there is no change made.

Type Parameters:

T - the type of object the Iterable contains

Parameters:

collection - the collection to get the input from, may be null

predicate - the predicate to use as a filter, may be null

Returns:

true if the collection is modified by this call, false otherwise.

filterInverse

public static  boolean filterInverse(Iterable collection,

Predicate predicate)

Filter the collection by applying a Predicate to each element. If the

predicate returns true, remove the element.

This is equivalent to filter(collection, PredicateUtils.notPredicate(predicate))

if predicate is != null.

If the input collection or predicate is null, there is no change made.

Type Parameters:

T - the type of object the Iterable contains

Parameters:

collection - the collection to get the input from, may be null

predicate - the predicate to use as a filter, may be null

Returns:

true if the collection is modified by this call, false otherwise.

transform

public static  void transform(Collection collection,

Transformer transformer)

Transform the collection by applying a Transformer to each element.

If the input collection or transformer is null, there is no change made.

This routine is best for Lists, for which set() is used to do the

transformations "in place." For other Collections, clear() and addAll()

are used to replace elements.

If the input collection controls its input, such as a Set, and the

Transformer creates duplicates (or are otherwise invalid), the collection

may reduce in size due to calling this method.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the Collection to get the input from, may be null

transformer - the transformer to perform, may be null

countMatches

@Deprecated

public static  int countMatches(Iterable input,

Predicate predicate)

Deprecated. since 4.1, use IterableUtils.countMatches(Iterable, Predicate) instead

Counts the number of elements in the input collection that match the

predicate.

A null collection or predicate matches no elements.

Type Parameters:

C - the type of object the Iterable contains

Parameters:

input - the Iterable to get the input from, may be null

predicate - the predicate to use, may be null

Returns:

the number of matches for the predicate in the collection

exists

@Deprecated

public static  boolean exists(Iterable input,

Predicate predicate)

Deprecated. since 4.1, use IterableUtils.matchesAny(Iterable, Predicate) instead

Answers true if a predicate is true for at least one element of a

collection.

A null collection or predicate returns false.

Type Parameters:

C - the type of object the Iterable contains

Parameters:

input - the Iterable to get the input from, may be null

predicate - the predicate to use, may be null

Returns:

true if at least one element of the collection matches the predicate

matchesAll

@Deprecated

public static  boolean matchesAll(Iterable input,

Predicate predicate)

Deprecated. since 4.1, use IterableUtils.matchesAll(Iterable, Predicate) instead

Answers true if a predicate is true for every element of a

collection.

A null predicate returns false.

A null or empty collection returns true.

Type Parameters:

C - the type of object the Iterable contains

Parameters:

input - the Iterable to get the input from, may be null

predicate - the predicate to use, may be null

Returns:

true if every element of the collection matches the predicate or if the

collection is empty, false otherwise

Since:

4.0

select

public static  Collection select(Iterable inputCollection,

Predicate predicate)

Selects all elements from input collection which match the given

predicate into an output collection.

A null predicate matches no elements.

Type Parameters:

O - the type of object the Iterable contains

Parameters:

inputCollection - the collection to get the input from, may not be null

predicate - the predicate to use, may be null

Returns:

the elements matching the predicate (new list)

Throws:

NullPointerException - if the input collection is null

select

public static > R select(Iterable inputCollection,

Predicate predicate,

R outputCollection)

Selects all elements from input collection which match the given

predicate and adds them to outputCollection.

If the input collection or predicate is null, there is no change to the

output collection.

Type Parameters:

O - the type of object the Iterable contains

R - the type of the output Collection

Parameters:

inputCollection - the collection to get the input from, may be null

predicate - the predicate to use, may be null

outputCollection - the collection to output into, may not be null if the inputCollection

and predicate or not null

Returns:

the outputCollection

select

public static > R select(Iterable inputCollection,

Predicate predicate,

R outputCollection,

R rejectedCollection)

Selects all elements from inputCollection into an output and rejected collection,

based on the evaluation of the given predicate.

Elements matching the predicate are added to the outputCollection,

all other elements are added to the rejectedCollection.

If the input predicate is null, no elements are added to

outputCollection or rejectedCollection.

Note: calling the method is equivalent to the following code snippet:

select(inputCollection, predicate, outputCollection);

selectRejected(inputCollection, predicate, rejectedCollection);

Type Parameters:

O - the type of object the Iterable contains

R - the type of the output Collection

Parameters:

inputCollection - the collection to get the input from, may be null

predicate - the predicate to use, may be null

outputCollection - the collection to output selected elements into, may not be null if the

inputCollection and predicate are not null

rejectedCollection - the collection to output rejected elements into, may not be null if the

inputCollection or predicate are not null

Returns:

the outputCollection

Since:

4.1

selectRejected

public static  Collection selectRejected(Iterable inputCollection,

Predicate predicate)

Selects all elements from inputCollection which don't match the given

predicate into an output collection.

If the input predicate is null, the result is an empty

list.

Type Parameters:

O - the type of object the Iterable contains

Parameters:

inputCollection - the collection to get the input from, may not be null

predicate - the predicate to use, may be null

Returns:

the elements not matching the predicate (new list)

Throws:

NullPointerException - if the input collection is null

selectRejected

public static > R selectRejected(Iterable inputCollection,

Predicate predicate,

R outputCollection)

Selects all elements from inputCollection which don't match the given

predicate and adds them to outputCollection.

If the input predicate is null, no elements are added to

outputCollection.

Type Parameters:

O - the type of object the Iterable contains

R - the type of the output Collection

Parameters:

inputCollection - the collection to get the input from, may be null

predicate - the predicate to use, may be null

outputCollection - the collection to output into, may not be null if the inputCollection

and predicate or not null

Returns:

outputCollection

collect

public static  Collection collect(Iterable inputCollection,

Transformer transformer)

Returns a new Collection containing all elements of the input collection

transformed by the given transformer.

If the input collection or transformer is null, the result is an empty list.

Type Parameters:

I - the type of object in the input collection

O - the type of object in the output collection

Parameters:

inputCollection - the collection to get the input from, may not be null

transformer - the transformer to use, may be null

Returns:

the transformed result (new list)

Throws:

NullPointerException - if the input collection is null

collect

public static  Collection collect(Iterator inputIterator,

Transformer transformer)

Transforms all elements from the input iterator with the given transformer

and adds them to the output collection.

If the input iterator or transformer is null, the result is an empty list.

Type Parameters:

I - the type of object in the input collection

O - the type of object in the output collection

Parameters:

inputIterator - the iterator to get the input from, may be null

transformer - the transformer to use, may be null

Returns:

the transformed result (new list)

collect

public static > R collect(Iterable inputCollection,

Transformer transformer,

R outputCollection)

Transforms all elements from input collection with the given transformer

and adds them to the output collection.

If the input collection or transformer is null, there is no change to the

output collection.

Type Parameters:

I - the type of object in the input collection

O - the type of object in the output collection

R - the type of the output collection

Parameters:

inputCollection - the collection to get the input from, may be null

transformer - the transformer to use, may be null

outputCollection - the collection to output into, may not be null if inputCollection

and transformer are not null

Returns:

the output collection with the transformed input added

Throws:

NullPointerException - if the outputCollection is null and both, inputCollection and

transformer are not null

collect

public static > R collect(Iterator inputIterator,

Transformer transformer,

R outputCollection)

Transforms all elements from the input iterator with the given transformer

and adds them to the output collection.

If the input iterator or transformer is null, there is no change to the

output collection.

Type Parameters:

I - the type of object in the input collection

O - the type of object in the output collection

R - the type of the output collection

Parameters:

inputIterator - the iterator to get the input from, may be null

transformer - the transformer to use, may be null

outputCollection - the collection to output into, may not be null if inputIterator

and transformer are not null

Returns:

the outputCollection with the transformed input added

Throws:

NullPointerException - if the output collection is null and both, inputIterator and

transformer are not null

addIgnoreNull

public static  boolean addIgnoreNull(Collection collection,

T object)

Adds an element to the collection unless the element is null.

Type Parameters:

T - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

object - the object to add, if null it will not be added

Returns:

true if the collection changed

Throws:

NullPointerException - if the collection is null

Since:

3.2

addAll

public static  boolean addAll(Collection collection,

Iterable iterable)

Adds all elements in the Iterable to the given collection. If the

Iterable is a Collection then it is cast and will be

added using Collection.addAll(Collection) instead of iterating.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

iterable - the iterable of elements to add, must not be null

Returns:

a boolean indicating whether the collection has changed or not.

Throws:

NullPointerException - if the collection or iterator is null

addAll

public static  boolean addAll(Collection collection,

Iterator iterator)

Adds all elements in the iteration to the given collection.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

iterator - the iterator of elements to add, must not be null

Returns:

a boolean indicating whether the collection has changed or not.

Throws:

NullPointerException - if the collection or iterator is null

addAll

public static  boolean addAll(Collection collection,

Enumeration enumeration)

Adds all elements in the enumeration to the given collection.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

enumeration - the enumeration of elements to add, must not be null

Returns:

true if the collections was changed, false otherwise

Throws:

NullPointerException - if the collection or enumeration is null

addAll

public static  boolean addAll(Collection collection,

C... elements)

Adds all elements in the array to the given collection.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

elements - the array of elements to add, must not be null

Returns:

true if the collection was changed, false otherwise

Throws:

NullPointerException - if the collection or array is null

get

@Deprecated

public static  T get(Iterator iterator,

int index)

Deprecated. since 4.1, use IteratorUtils.get(Iterator, int) instead

Returns the index-th value in Iterator, throwing

IndexOutOfBoundsException if there is no such element.

The Iterator is advanced to index (or to the end, if

index exceeds the number of entries) as a side effect of this method.

Type Parameters:

T - the type of object in the Iterator

Parameters:

iterator - the iterator to get a value from

index - the index to get

Returns:

the object at the specified index

Throws:

IndexOutOfBoundsException - if the index is invalid

IllegalArgumentException - if the object type is invalid

get

@Deprecated

public static  T get(Iterable iterable,

int index)

Deprecated. since 4.1, use IterableUtils.get(Iterable, int) instead

Returns the index-th value in the iterable's Iterator, throwing

IndexOutOfBoundsException if there is no such element.

If the Iterable is a List, then it will use List.get(int).

Type Parameters:

T - the type of object in the Iterable.

Parameters:

iterable - the Iterable to get a value from

index - the index to get

Returns:

the object at the specified index

Throws:

IndexOutOfBoundsException - if the index is invalid

get

public static Object get(Object object,

int index)

Returns the index-th value in object, throwing

IndexOutOfBoundsException if there is no such element or

IllegalArgumentException if object is not an

instance of one of the supported types.

The supported types, and associated semantics are:

Map -- the value returned is the Map.Entry in position

index in the map's entrySet iterator,

if there is such an entry.

List -- this method is equivalent to the list's get method.

Array -- the index-th array entry is returned,

if there is such an entry; otherwise an IndexOutOfBoundsException

is thrown.

Collection -- the value returned is the index-th object

returned by the collection's default iterator, if there is such an element.

Iterator or Enumeration -- the value returned is the

index-th object in the Iterator/Enumeration, if there

is such an element. The Iterator/Enumeration is advanced to

index (or to the end, if index exceeds the

number of entries) as a side effect of this method.

Parameters:

object - the object to get a value from

index - the index to get

Returns:

the object at the specified index

Throws:

IndexOutOfBoundsException - if the index is invalid

IllegalArgumentException - if the object type is invalid

get

public static  Map.Entry get(Map map,

int index)

Returns the index-th Map.Entry in the map's entrySet,

throwing IndexOutOfBoundsException if there is no such element.

Type Parameters:

K - the key type in the Map

V - the key type in the Map

Parameters:

map - the object to get a value from

index - the index to get

Returns:

the object at the specified index

Throws:

IndexOutOfBoundsException - if the index is invalid

size

public static int size(Object object)

Gets the size of the collection/iterator specified.

This method can handles objects as follows

Collection - the collection size

Map - the map size

Array - the array size

Iterator - the number of elements remaining in the iterator

Enumeration - the number of elements remaining in the enumeration

Parameters:

object - the object to get the size of, may be null

Returns:

the size of the specified collection or 0 if the object was null

Throws:

IllegalArgumentException - thrown if object is not recognized

Since:

3.1

sizeIsEmpty

public static boolean sizeIsEmpty(Object object)

Checks if the specified collection/array/iterator is empty.

This method can handles objects as follows

Collection - via collection isEmpty

Map - via map isEmpty

Array - using array size

Iterator - via hasNext

Enumeration - via hasMoreElements

Note: This method is named to avoid clashing with

isEmpty(Collection).

Parameters:

object - the object to get the size of, may be null

Returns:

true if empty or null

Throws:

IllegalArgumentException - thrown if object is not recognized

Since:

3.2

isEmpty

public static boolean isEmpty(Collection coll)

Null-safe check if the specified collection is empty.

Null returns true.

Parameters:

coll - the collection to check, may be null

Returns:

true if empty or null

Since:

3.2

isNotEmpty

public static boolean isNotEmpty(Collection coll)

Null-safe check if the specified collection is not empty.

Null returns false.

Parameters:

coll - the collection to check, may be null

Returns:

true if non-null and non-empty

Since:

3.2

reverseArray

public static void reverseArray(Object[] array)

Reverses the order of the given array.

Parameters:

array - the array to reverse

isFull

public static boolean isFull(Collection coll)

Returns true if no more elements can be added to the Collection.

This method uses the BoundedCollection interface to determine the

full status. If the collection does not implement this interface then

false is returned.

The collection does not have to implement this interface directly.

If the collection has been decorated using the decorators subpackage

then these will be removed to access the BoundedCollection.

Parameters:

coll - the collection to check

Returns:

true if the BoundedCollection is full

Throws:

NullPointerException - if the collection is null

maxSize

public static int maxSize(Collection coll)

Get the maximum number of elements that the Collection can contain.

This method uses the BoundedCollection interface to determine the

maximum size. If the collection does not implement this interface then

-1 is returned.

The collection does not have to implement this interface directly.

If the collection has been decorated using the decorators subpackage

then these will be removed to access the BoundedCollection.

Parameters:

coll - the collection to check

Returns:

the maximum size of the BoundedCollection, -1 if no maximum size

Throws:

NullPointerException - if the collection is null

collate

public static > List collate(Iterable a,

Iterable b)

Merges two sorted Collections, a and b, into a single, sorted List

such that the natural ordering of the elements is retained.

Uses the standard O(n) merge algorithm for combining two sorted lists.

Type Parameters:

O - the element type

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

Returns:

a new sorted List, containing the elements of Collection a and b

Throws:

NullPointerException - if either collection is null

Since:

4.0

collate

public static > List collate(Iterable a,

Iterable b,

boolean includeDuplicates)

Merges two sorted Collections, a and b, into a single, sorted List

such that the natural ordering of the elements is retained.

Uses the standard O(n) merge algorithm for combining two sorted lists.

Type Parameters:

O - the element type

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

includeDuplicates - if true duplicate elements will be retained, otherwise

they will be removed in the output collection

Returns:

a new sorted List, containing the elements of Collection a and b

Throws:

NullPointerException - if either collection is null

Since:

4.0

collate

public static  List collate(Iterable a,

Iterable b,

Comparator c)

Merges two sorted Collections, a and b, into a single, sorted List

such that the ordering of the elements according to Comparator c is retained.

Uses the standard O(n) merge algorithm for combining two sorted lists.

Type Parameters:

O - the element type

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

c - the comparator to use for the merge.

Returns:

a new sorted List, containing the elements of Collection a and b

Throws:

NullPointerException - if either collection or the comparator is null

Since:

4.0

collate

public static  List collate(Iterable a,

Iterable b,

Comparator c,

boolean includeDuplicates)

Merges two sorted Collections, a and b, into a single, sorted List

such that the ordering of the elements according to Comparator c is retained.

Uses the standard O(n) merge algorithm for combining two sorted lists.

Type Parameters:

O - the element type

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

c - the comparator to use for the merge.

includeDuplicates - if true duplicate elements will be retained, otherwise

they will be removed in the output collection

Returns:

a new sorted List, containing the elements of Collection a and b

Throws:

NullPointerException - if either collection or the comparator is null

Since:

4.0

permutations

public static  Collection> permutations(Collection collection)

Returns a Collection of all the permutations of the input collection.

NOTE: the number of permutations of a given collection is equal to n!, where

n is the size of the collection. Thus, the resulting collection will become

very large for collections > 10 (e.g. 10! = 3628800, 15! = 1307674368000).

For larger collections it is advised to use a PermutationIterator to

iterate over all permutations.

Type Parameters:

E - the element type

Parameters:

collection - the collection to create permutations for, may not be null

Returns:

an unordered collection of all permutations of the input collection

Throws:

NullPointerException - if collection is null

Since:

4.0

See Also:

PermutationIterator

retainAll

public static  Collection retainAll(Collection collection,

Collection retain)

Returns a collection containing all the elements in collection

that are also in retain. The cardinality of an element e

in the returned collection is the same as the cardinality of e

in collection unless retain does not contain e, in which

case the cardinality is zero. This method is useful if you do not wish to modify

the collection c and thus cannot call c.retainAll(retain);.

This implementation iterates over collection, checking each element in

turn to see if it's contained in retain. If it's contained, it's added

to the returned list. As a consequence, it is advised to use a collection type for

retain that provides a fast (e.g. O(1)) implementation of

Collection.contains(Object).

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection whose contents are the target of the #retailAll operation

retain - the collection containing the elements to be retained in the returned collection

Returns:

a Collection containing all the elements of collection

that occur at least once in retain.

Throws:

NullPointerException - if either parameter is null

Since:

3.2

retainAll

public static  Collection retainAll(Iterable collection,

Iterable retain,

Equator equator)

Returns a collection containing all the elements in

collection that are also in retain. The

cardinality of an element e in the returned collection is

the same as the cardinality of e in collection

unless retain does not contain e, in which case

the cardinality is zero. This method is useful if you do not wish to

modify the collection c and thus cannot call

c.retainAll(retain);.

Moreover this method uses an Equator instead of

Object.equals(Object) to determine the equality of the elements

in collection and retain. Hence this method is

useful in cases where the equals behavior of an object needs to be

modified without changing the object itself.

Type Parameters:

E - the type of object the Collection contains

Parameters:

collection - the collection whose contents are the target of the retainAll operation

retain - the collection containing the elements to be retained in the returned collection

equator - the Equator used for testing equality

Returns:

a Collection containing all the elements of collection

that occur at least once in retain according to the equator

Throws:

NullPointerException - if any of the parameters is null

Since:

4.1

removeAll

public static  Collection removeAll(Collection collection,

Collection remove)

Removes the elements in remove from collection. That is, this

method returns a collection containing all the elements in c

that are not in remove. The cardinality of an element e

in the returned collection is the same as the cardinality of e

in collection unless remove contains e, in which

case the cardinality is zero. This method is useful if you do not wish to modify

the collection c and thus cannot call collection.removeAll(remove);.

This implementation iterates over collection, checking each element in

turn to see if it's contained in remove. If it's not contained, it's added

to the returned list. As a consequence, it is advised to use a collection type for

remove that provides a fast (e.g. O(1)) implementation of

Collection.contains(Object).

Type Parameters:

E - the type of object the Collection contains

Parameters:

collection - the collection from which items are removed (in the returned collection)

remove - the items to be removed from the returned collection

Returns:

a Collection containing all the elements of collection except

any elements that also occur in remove.

Throws:

NullPointerException - if either parameter is null

Since:

4.0 (method existed in 3.2 but was completely broken)

removeAll

public static  Collection removeAll(Iterable collection,

Iterable remove,

Equator equator)

Removes all elements in remove from collection.

That is, this method returns a collection containing all the elements in

collection that are not in remove. The

cardinality of an element e in the returned collection is

the same as the cardinality of e in collection

unless remove contains e, in which case the

cardinality is zero. This method is useful if you do not wish to modify

the collection c and thus cannot call

collection.removeAll(remove).

Moreover this method uses an Equator instead of

Object.equals(Object) to determine the equality of the elements

in collection and remove. Hence this method is

useful in cases where the equals behavior of an object needs to be

modified without changing the object itself.

Type Parameters:

E - the type of object the Collection contains

Parameters:

collection - the collection from which items are removed (in the returned collection)

remove - the items to be removed from the returned collection

equator - the Equator used for testing equality

Returns:

a Collection containing all the elements of collection

except any element that if equal according to the equator

Throws:

NullPointerException - if any of the parameters is null

Since:

4.1

synchronizedCollection

@Deprecated

public static  Collection synchronizedCollection(Collection collection)

Deprecated. since 4.1, use Collections.synchronizedCollection(Collection) instead

Returns a synchronized collection backed by the given collection.

You must manually synchronize on the returned buffer's iterator to

avoid non-deterministic behavior:

Collection c = CollectionUtils.synchronizedCollection(myCollection);

synchronized (c) {

Iterator i = c.iterator();

while (i.hasNext()) {

process (i.next());

}

}

This method uses the implementation in the decorators subpackage.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to synchronize, must not be null

Returns:

a synchronized collection backed by the given collection

Throws:

NullPointerException - if the collection is null

unmodifiableCollection

@Deprecated

public static  Collection unmodifiableCollection(Collection collection)

Deprecated. since 4.1, use Collections.unmodifiableCollection(Collection) instead

Returns an unmodifiable collection backed by the given collection.

This method uses the implementation in the decorators subpackage.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to make unmodifiable, must not be null

Returns:

an unmodifiable collection backed by the given collection

Throws:

NullPointerException - if the collection is null

predicatedCollection

public static  Collection predicatedCollection(Collection collection,

Predicate predicate)

Returns a predicated (validating) collection backed by the given collection.

Only objects that pass the test in the given predicate can be added to the collection.

Trying to add an invalid object results in an IllegalArgumentException.

It is important not to use the original collection after invoking this method,

as it is a backdoor for adding invalid objects.

Type Parameters:

C - the type of objects in the Collection.

Parameters:

collection - the collection to predicate, must not be null

predicate - the predicate for the collection, must not be null

Returns:

a predicated collection backed by the given collection

Throws:

NullPointerException - if the Collection is null

transformingCollection

public static  Collection transformingCollection(Collection collection,

Transformer transformer)

Returns a transformed bag backed by the given collection.

Each object is passed through the transformer as it is added to the

Collection. It is important not to use the original collection after invoking this

method, as it is a backdoor for adding untransformed objects.

Existing entries in the specified collection will not be transformed.

If you want that behaviour, see TransformedCollection.transformedCollection(java.util.Collection, org.apache.commons.collections4.Transformer).

Type Parameters:

E - the type of object the Collection contains

Parameters:

collection - the collection to predicate, must not be null

transformer - the transformer for the collection, must not be null

Returns:

a transformed collection backed by the given collection

Throws:

NullPointerException - if the Collection or Transformer is null

extractSingleton

public static  E extractSingleton(Collection collection)

Extract the lone element of the specified Collection.

Type Parameters:

E - collection type

Parameters:

collection - to read

Returns:

sole member of collection

Throws:

NullPointerException - if collection is null

IllegalArgumentException - if collection is empty or contains more than one element

Since:

4.0

Skip navigation links

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Prev Class

Next Class

Frames

No Frames

All Classes

Summary: 

Nested | 

Field | 

Constr | 

Method

Detail: 

Field | 

Constr | 

Method

Copyright © 2001–2019 The Apache Software Foundation. All rights reserved.

Spring自带的CollectionUtils工具类_spring collectionutils-CSDN博客