net.sourceforge.pmd.util

## Class CollectionUtil

- java.lang.Object
- - net.sourceforge.pmd.util.CollectionUtil

    public final class CollectionUtil
    extends Object

Generic collection and array-related utility functions for java.util types. See ClassUtil for comparable facilities for short name lookup.

Version:
  $Revision$
Author:
  Brian Remedios

### Field Summary

Fields
`static TypeMap` `COLLECTION_CLASSES_BY_NAMES`
`static TypeMap` `COLLECTION_INTERFACES_BY_NAMES`

### Method Summary

Methods
`static int` `addWithoutDuplicates(Collection<String> source, Collection<String> target)` Add elements from the source to the target as long as they don't already exist there.
`static <T> T[]` `addWithoutDuplicates(T[] values, T newValue)` If the newValue is already held within the values array then the values array is returned, otherwise a new array is created appending the newValue to the end.
`static <T> T[]` `addWithoutDuplicates(T[] values, T[] newValues)` Returns an array of values as a union set of the two input arrays.
`static boolean` `areEqual(Object value, Object otherValue)` A comprehensive isEqual method that handles nulls and arrays safely.
`static <T> boolean` `areSemanticEquals(T[] a, T[] b)` Returns true if both arrays are if both are null or have zero-length, otherwise return the false if their respective elements are not equal by position.
`static boolean` `arraysAreEqual(Object value, Object otherValue)` Returns true if the objects are array instances and each of their elements compares via equals as well.
`static <T> Set<T>` `asSet(T[] items)` Returns the items as a populated set.
`static Class<?>` `getCollectionTypeFor(String shortName)` Returns the collection type if we recognize it by its short name.
`static <K,V> Map<V,K>` `invertedMapFrom(Map<K,V> source)` Returns a map based on the source but with the key & values swapped.
`static boolean` `isCollectionType(Class<?> clazzType, boolean includeInterfaces)` Return whether we can identify the typeName as a java.util collection class or interface as specified.
`static boolean` `isCollectionType(String typeName, boolean includeInterfaces)` Return whether we can identify the typeName as a java.util collection class or interface as specified.
`static boolean` `isEmpty(Object[] items)` Returns whether the items array is null or has zero length.
`static boolean` `isNotEmpty(Object[] items)` Returns whether the items array is non-null and has at least one entry.
`static <K,V> Map<K,V>` `mapFrom(K[] keys, V[] values)` Creates and returns a map populated with the keyValuesSets where the value held by the tuples are they key and value in that order.
`static boolean` `valuesAreTransitivelyEqual(Object[] thisArray, Object[] thatArray)` Returns whether the arrays are equal by examining each of their elements, even if they are arrays themselves.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### COLLECTION_INTERFACES_BY_NAMES

    public static final TypeMap COLLECTION_INTERFACES_BY_NAMES

#### COLLECTION_CLASSES_BY_NAMES

    public static final TypeMap COLLECTION_CLASSES_BY_NAMES

### Method Detail

#### addWithoutDuplicates

    public static int addWithoutDuplicates(Collection<String> source,
                           Collection<String> target)

Add elements from the source to the target as long as they don't already exist there. Return the number of items actually added.

Parameters:
  `source` -
  `target` -
Returns:
  int

#### getCollectionTypeFor

    public static Class<?> getCollectionTypeFor(String shortName)

Returns the collection type if we recognize it by its short name.

Parameters:
  `shortName` - String
Returns:
  Class

#### isCollectionType

    public static boolean isCollectionType(String typeName,
                           boolean includeInterfaces)

Return whether we can identify the typeName as a java.util collection class or interface as specified.

Parameters:
  `typeName` - String
  `includeInterfaces` - boolean
Returns:
  boolean

#### isCollectionType

    public static boolean isCollectionType(Class<?> clazzType,
                           boolean includeInterfaces)

Return whether we can identify the typeName as a java.util collection class or interface as specified.

Parameters:
  `clazzType` - Class
  `includeInterfaces` - boolean
Returns:
  boolean

#### asSet

    public static <T> Set<T> asSet(T[] items)

Returns the items as a populated set.

Parameters:
  `items` - Object[]
Returns:
  Set

#### mapFrom

    public static <K,V> Map<K,V> mapFrom(K[] keys,
                         V[] values)

Creates and returns a map populated with the keyValuesSets where the value held by the tuples are they key and value in that order.

Parameters:
  `keys` - K[]
  `values` - V[]
Returns:
  Map

#### invertedMapFrom

    public static <K,V> Map<V,K> invertedMapFrom(Map<K,V> source)

Returns a map based on the source but with the key & values swapped.

Parameters:
  `source` - Map
Returns:
  Map

#### arraysAreEqual

    public static boolean arraysAreEqual(Object value,
                         Object otherValue)

Returns true if the objects are array instances and each of their elements compares via equals as well.

Parameters:
  `value` - Object
  `otherValue` - Object
Returns:
  boolean

#### valuesAreTransitivelyEqual

    public static boolean valuesAreTransitivelyEqual(Object[] thisArray,
                                     Object[] thatArray)

Returns whether the arrays are equal by examining each of their elements, even if they are arrays themselves.

Parameters:
  `thisArray` - Object[]
  `thatArray` - Object[]
Returns:
  boolean

#### areEqual

    public static boolean areEqual(Object value,
                   Object otherValue)

A comprehensive isEqual method that handles nulls and arrays safely.

Parameters:
  `value` - Object
  `otherValue` - Object
Returns:
  boolean

#### isEmpty

    public static boolean isEmpty(Object[] items)

Returns whether the items array is null or has zero length.

Parameters:
  `items` -
Returns:
  boolean

#### isNotEmpty

    public static boolean isNotEmpty(Object[] items)

Returns whether the items array is non-null and has at least one entry.

Parameters:
  `items` -
Returns:
  boolean

#### areSemanticEquals

    public static <T> boolean areSemanticEquals(T[] a,
                                T[] b)

Returns true if both arrays are if both are null or have zero-length, otherwise return the false if their respective elements are not equal by position.

Type Parameters:
  `T` -
Parameters:
  `a` -
  `b` -
Returns:
  boolean

#### addWithoutDuplicates

    public static <T> T[] addWithoutDuplicates(T[] values,
                               T newValue)

If the newValue is already held within the values array then the values array is returned, otherwise a new array is created appending the newValue to the end.

Type Parameters:
  `T` -
Parameters:
  `values` -
  `newValue` -
Returns:
  an array containing the union of values and newValue

#### addWithoutDuplicates

    public static <T> T[] addWithoutDuplicates(T[] values,
                               T[] newValues)

Returns an array of values as a union set of the two input arrays.

Type Parameters:
  `T` -
Parameters:
  `values` -
  `newValues` -
Returns:
  the union of the two arrays