# Class: com.pnfsoftware.jeb.util.collect.CollectionUtil

Convenience methods for Java [collections](Collection), in particular, [lists](List).

## Static Method: addNonNulls
- parameter: `dst`, type: `java.util.Collection<T>`
- parameter: `src`, type: `java.util.Collection<? extends T>`
- return type: `java.util.Collection<T>`

Description: Add all non\-null source elements to a destination collection.
parameter: T: element type
parameter: dst: destination collection
parameter: src: optional source collection
return: the destination collection

## Static Method: addNonNulls
- parameter: `dst`, type: `java.util.Collection<T>`
- parameter: `elts`, type: `T[]`
- return type: `java.util.Collection<T>`

Description: Add all non\-null elements to a destination collection.
parameter: T: element type
parameter: dst: destination collection
parameter: elts: optional elements
return: the destination collection

## Static Method: binarySearch
- parameter: `list`, type: `java.util.List<T>`
- parameter: `key`, type: `K`
- parameter: `extractor`, type: `com.pnfsoftware.jeb.util.collect.IExtractor<T,K>`
- return type: `T`

Description: Perform a binary search in an ordered list.
parameter: T: element type
parameter: K: key type
parameter: list: a list of ordered items
parameter: key: the ordering key for the items.
parameter: extractor: key extractor
return: the element, null if not found

## Static Method: binarySearchEx
- parameter: `list`, type: `java.util.List<? extends T>`
- parameter: `key`, type: `K`
- parameter: `extractor`, type: `com.pnfsoftware.jeb.util.collect.IExtractor<T,? extends K>`
- parameter: `cc`, type: `java.util.Comparator<K>`
- return type: `int`

Description: Perform a binary search in an ordered list.
parameter: T: element type
parameter: K: key type
parameter: list: a list of ordered items
parameter: key: the ordering key for the items.
parameter: extractor: key extractor
parameter: cc: optional custom comparator for the keys
return: the zero\+ index of the found element; else, the negative insertion index of the ghost         element

## Static Method: compare
- parameter: `c1`, type: `java.util.Collection<? extends T>`
- parameter: `c2`, type: `java.util.Collection<? extends T>`
- parameter: `sorted`, type: `boolean`
- return type: `boolean`

Description: Compare two collections using element equality.
parameter: T: element type
parameter: c1: first collection
parameter: c2: second collection
parameter: sorted: true if iteration order must be considered
return: true if the collections contain the same elements

## Static Method: compareByReference
- parameter: `c1`, type: `java.util.Collection<? extends T>`
- parameter: `c2`, type: `java.util.Collection<? extends T>`
- parameter: `sorted`, type: `boolean`
- return type: `boolean`

Description: Compare two collections using reference identity for elements.
parameter: T: element type
parameter: c1: first collection
parameter: c2: second collection
parameter: sorted: true if iteration order must be considered
return: true if the collections contain the same references

## Static Method: contains
- parameter: `c`, type: `java.util.Collection<?>`
- parameter: `v`, type: `java.lang.Object`
- return type: `boolean`

Description: Safely check if an object is present within a collection.
parameter: c: collection, potentially null
parameter: v: object, potentially null
return: true IFF the object is contained in the collection

## Static Method: containsNonNull
- parameter: `c`, type: `java.lang.Iterable<?>`
- return type: `boolean`

Description: Determine if the given iterable contains one or more non\-null elements.
parameter: c: iterable to inspect
return: true if at least one element is not null

## Static Method: containsNull
- parameter: `c`, type: `java.lang.Iterable<?>`
- return type: `boolean`

Description: Determine if the given iterable contains one or more null elements.
parameter: c: iterable to inspect
return: true if at least one element is null

## Static Method: containsReference
- parameter: `c`, type: `java.util.Collection<? extends T>`
- parameter: `o`, type: `T`
- return type: `boolean`

Description: Determine if the collection contains the object reference \(differs from [Collection#contains(Object)](Collection#contains(Object)) by checking reference equality ` == ` instead of [Object#equals(Object)](Object#equals(Object)) equality\)
parameter: T: element type
parameter: c: collection to loop into
parameter: o: element whose presence in this collection is to be tested
return: true if the collection contains the specified element

## Static Method: count
- parameter: `coll`, type: `java.util.Collection<T>`
- parameter: `item`, type: `T`
- return type: `int`

Description: Count elements using [Object#equals(Object)](Object#equals(Object)).
parameter: T: element type
parameter: coll: collection to inspect
parameter: item: item to count
return: number of equal elements

## Static Method: doubleCollectionIterable
- parameter: `coll1`, type: `java.util.Collection<T>`
- parameter: `coll2`, type: `java.util.Collection<T>`
- return type: `java.lang.Iterable<T>`

Description: Create a generator that will iterate over two collections, starting with the first one, then the second one. 

 This method is convenient to iterate over two collections without having to create an intermediate list holding the elements.
parameter: T: element type
parameter: coll1: first collection
parameter: coll2: second collection
return: an iterable

## Static Method: first
- parameter: `coll`, type: `java.util.Collection<T>`
- return type: `T`

Description: Retrieve the first item of a [Collection](Collection). This method is safe and returns null if the collection is null or empty.
parameter: T: element type
parameter: coll: a collection
return: the first item or null if collection is null or empty

## Static Method: hasIntersection
- parameter: `c1`, type: `java.util.Collection<? extends T>`
- parameter: `c2`, type: `java.util.Collection<? extends T>`
- return type: `boolean`

Description: Determine whether two collections share at least one element.
parameter: T: element type
parameter: c1: first collection
parameter: c2: second collection
return: true if both collections contain at least one equal element

## Static Method: identityCount
- parameter: `coll`, type: `java.util.Collection<T>`
- parameter: `item`, type: `T`
- return type: `int`

Description: Count elements using `==`.
parameter: T: element type
parameter: coll: collection to inspect
parameter: item: item to count
return: number of identical elements

## Static Method: intersect
- parameter: `c1`, type: `java.util.Collection<? extends T>`
- parameter: `c2`, type: `java.util.Collection<? extends T>`
- return type: `java.util.Set<T>`

Description: Return the intersection of 2 collections \(order of collection parameters does not matter\).
parameter: T: element type
parameter: c1: first collection
parameter: c2: second collection
return: a set of intersection

## Static Method: last
- parameter: `coll`, type: `java.util.Collection<T>`
- return type: `T`

Description: Retrieve the last item of a [Collection](Collection). This method is safe and returns null if the collection is null or empty.
parameter: T: element type
parameter: coll: a collection
return: the last item or null if collection is null or empty

