CollectionUtil (Fujion Common Library 3.1.0 API)

java.lang.Object
- org.fujion.common.CollectionUtil

public class CollectionUtil
extends Object

Utility methods for manipulating collections.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static <CT extends Collection<T>,CS extends Collection<S>,T,S> CS`	`castCollection(CT collection, Class<S> clazz)` Casts a collection containing elements of class T to a collection containing elements of a class S where S must be assignment-compatible with T.
`static <T,S> List<S>`	`castList(List<T> list, Class<S> clazz)` Casts a list containing elements of class T to a list containing elements of a class S where S must be assignment-compatible with T.
`static boolean`	`containsInstance(List<?> list, Object object)` Returns true if the list contains the exact instance of the specified object.
`static <T> List<T>`	`ensureList(List<T> list)` Ensures that the list is not null, creating one if it is.
`static <T,I> T`	`findMatch(Collection<T> source, BiPredicate<T,I> criteria, I... items)` Searches a list of items for the first one that matches an element from the source collection based on the criteria provided, returning the matching element.
`static <T> T`	`findMatch(Collection<T> source, Predicate<T> criteria)` Searches a collection for the first element that matches the specified criteria.
`static <T> List<T>`	`findMatches(Collection<T> source, Predicate<T> criteria)` Searches a collection for the all elements that match the specified criteria.
`static <T> T`	`getFirst(Collection<T> source)` Returns the first element of a collection, or null if the collection is null or empty.
`static int`	`indexOfInstance(List<?> list, Object object)` Performs a lookup for the exact instance of an object in the list and returns its index, or -1 if not found.
`static boolean`	`intersects(Iterable<?> iter1, Iterable<?> iter2)` Returns true if the two iterables intersect (i.e., have at least one element in common).
`static boolean`	`intersects(Object[] ary1, Object[] ary2)` Returns true if the two arrays intersect (i.e., have at least one element in common).
`static boolean`	`isEmpty(Collection<?> source)` Returns true if the collection is null or empty.
`static <T,S extends T> Iterable<S>`	`iterableForType(Collection<T> collection, Class<S> type)` Returns an iterable that produces only collection members of the specified type.
`static <T,S extends T> Iterator<S>`	`iteratorForType(Collection<T> collection, Class<S> type)` Returns a list iterator that produces only collection elements of the specified type.
`static <T,S extends T> Iterator<S>`	`iteratorForType(Iterator<T> iterator, Class<S> type)` Returns an iterator that returns only elements of the specified type.
`static boolean`	`notEmpty(Collection<?> source)` Returns true if the collection is not empty.
`static <T> List<T>`	`replaceElements(List<T> dest, Collection<T> source)` Replaces the contents of the destination list with that of the source list.
`static <T> List<T>`	`replaceElements(List<T> dest, T... elements)` Replaces the contents of the destination list with the specified elements.
`static <T> List<T>`	`toList(T... elements)` Converts an array to a list, handling nulls.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getFirst
```
public static <T> T getFirst(Collection<T> source)
```
    Returns the first element of a collection, or null if the collection is null or empty.
    
    Type Parameters:
    
    T - The collection element type.
    
    Parameters:
    
    source - The collection.
    
    Returns:
    
    The first element (possibly null).
  - isEmpty
```
public static boolean isEmpty(Collection<?> source)
```
    Returns true if the collection is null or empty.
    
    Parameters:
    
    source - The collection.
    
    Returns:
    
    True if the collection is null or empty.
  - notEmpty
```
public static boolean notEmpty(Collection<?> source)
```
    Returns true if the collection is not empty.
    
    Parameters:
    
    source - The collection.
    
    Returns:
    
    True if the collection is not empty.
  - containsInstance
```
public static boolean containsInstance(List<?> list,
                                       Object object)
```
    Returns true if the list contains the exact instance of the specified object.
    
    Parameters:
    
    list - List to search.
    
    object - Object instance to locate.
    
    Returns:
    
    True if the object was found.
  - indexOfInstance
```
public static int indexOfInstance(List<?> list,
                                  Object object)
```
    Performs a lookup for the exact instance of an object in the list and returns its index, or -1 if not found. This is different from the usual implementation of a list search that uses the object's equals implementation.
    
    Parameters:
    
    list - List to search.
    
    object - Object instance to locate.
    
    Returns:
    
    Index of the object.
  - castList
```
public static <T,S> List<S> castList(List<T> list,
                                     Class<S> clazz)
```
    Casts a list containing elements of class T to a list containing elements of a class S where S must be assignment-compatible with T.
    
    Type Parameters:
    
    T - Class of list elements.
    
    S - Target class for cast.
    
    Parameters:
    
    list - List to be recast.
    
    clazz - Class to which to cast list elements.
    
    Returns:
    
    The recast list.
  - castCollection
```
public static <CT extends Collection<T>,CS extends Collection<S>,T,S> CS castCollection(CT collection,
                                                                                        Class<S> clazz)
```
    Casts a collection containing elements of class T to a collection containing elements of a class S where S must be assignment-compatible with T.
    
    Type Parameters:
    
    T - Class of collection elements.
    
    CT - Class of Collection of T elements.
    
    S - Target class for cast.
    
    CS - Class of Collection of S elements.
    
    Parameters:
    
    collection - Collection to be recast.
    
    clazz - Class to which to cast collection elements.
    
    Returns:
    
    The recast collection.
  - iteratorForType
```
public static <T,S extends T> Iterator<S> iteratorForType(Collection<T> collection,
                                                          Class<S> type)
```
    Returns a list iterator that produces only collection elements of the specified type.
    
    Type Parameters:
    
    T - Class of collection elements.
    
    S - Subclass of T to be used by iterator.
    
    Parameters:
    
    collection - Collection to iterate.
    
    type - Type of element to return.
    
    Returns:
    
    An iterator.
  - iteratorForType
```
public static <T,S extends T> Iterator<S> iteratorForType(Iterator<T> iterator,
                                                          Class<S> type)
```
    Returns an iterator that returns only elements of the specified type.
    
    Type Parameters:
    
    T - Class of collection elements.
    
    S - Subclass of T to be used by iterator.
    
    Parameters:
    
    iterator - Iterator to wrap.
    
    type - Type of element to return.
    
    Returns:
    
    An iterator.
  - iterableForType
```
public static <T,S extends T> Iterable<S> iterableForType(Collection<T> collection,
                                                          Class<S> type)
```
    Returns an iterable that produces only collection members of the specified type.
    
    Type Parameters:
    
    T - Class of collection elements.
    
    S - Subclass of T to be used by iterable.
    
    Parameters:
    
    collection - Collection to iterate.
    
    type - Type of element to return.
    
    Returns:
    
    An iterable.
  - intersects
```
public static boolean intersects(Object[] ary1,
                                 Object[] ary2)
```
    Returns true if the two arrays intersect (i.e., have at least one element in common).
    
    Parameters:
    
    ary1 - The first array.
    
    ary2 - The second array.
    
    Returns:
    
    True if the two arrays intersect.
  - intersects
```
public static boolean intersects(Iterable<?> iter1,
                                 Iterable<?> iter2)
```
    Returns true if the two iterables intersect (i.e., have at least one element in common).
    
    Parameters:
    
    iter1 - The first iterable.
    
    iter2 - The second iterable.
    
    Returns:
    
    True if the two iterables intersect.
  - toList
```
public static <T> List<T> toList(T... elements)
```
    Converts an array to a list, handling nulls.
    
    Type Parameters:
    
    T - The element type.
    
    Parameters:
    
    elements - The array of elements.
    
    Returns:
    
    The list containing the elements (null if input was null).
  - ensureList
```
public static <T> List<T> ensureList(List<T> list)
```
    Ensures that the list is not null, creating one if it is.
    
    Type Parameters:
    
    T - The list's element type.
    
    Parameters:
    
    list - The list.
    
    Returns:
    
    The original list, or a new one if the original was null.
  - replaceElements
```
public static <T> List<T> replaceElements(List<T> dest,
                                          Collection<T> source)
```
    Replaces the contents of the destination list with that of the source list.
    
    Type Parameters:
    
    T - The lists' element type.
    
    Parameters:
    
    dest - The destination list. If null, a new list will be created.
    
    source - The source list. Null is equivalent to an empty list.
    
    Returns:
    
    The modified (or newly created) destination list.
  - replaceElements
```
public static <T> List<T> replaceElements(List<T> dest,
                                          T... elements)
```
    Replaces the contents of the destination list with the specified elements.
    
    Type Parameters:
    
    T - The lists' element type.
    
    Parameters:
    
    dest - The destination list. If null, a new list will be created.
    
    elements - A list of elements to be copied to the destination list.
    
    Returns:
    
    The modified (or newly created) destination list.
  - findMatch
```
public static <T> T findMatch(Collection<T> source,
                              Predicate<T> criteria)
```
    Searches a collection for the first element that matches the specified criteria.
    
    Type Parameters:
    
    T - The type of collection element.
    
    Parameters:
    
    source - The collection to search.
    
    criteria - The criteria for a matching element.
    
    Returns:
    
    The matching element, or null if not found.
  - findMatch
```
public static <T,I> T findMatch(Collection<T> source,
                                BiPredicate<T,I> criteria,
                                I... items)
```
    Searches a list of items for the first one that matches an element from the source collection based on the criteria provided, returning the matching element.
    
    Type Parameters:
    
    T - The type of collection element.
    
    I - The type of item.
    
    Parameters:
    
    source - The collection to search.
    
    criteria - The criteria for a matching element.
    
    items - The list of items to search.
    
    Returns:
    
    The matching element, or null if not found.
  - findMatches
```
public static <T> List<T> findMatches(Collection<T> source,
                                      Predicate<T> criteria)
```
    Searches a collection for the all elements that match the specified criteria.
    
    Type Parameters:
    
    T - The type of collection element.
    
    Parameters:
    
    source - The collection to search.
    
    criteria - The criteria for a matching element.
    
    Returns:
    
    The list of matching elements (never null);

Class CollectionUtil

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getFirst

isEmpty

notEmpty

containsInstance

indexOfInstance

castList

castCollection

iteratorForType

iteratorForType

iterableForType

intersects

intersects

toList

ensureList

replaceElements

replaceElements

findMatch

findMatch

findMatches