kodkod.util.collections

Class Containers

java.lang.Object

kodkod.util.collections.Containers

public final class Containers
extends Object

Provides utility methods for working with arrays and collections.

Author:

Emina Torlak

Method Summary

Modifier and Type	Method and Description
static <T> Set<T>	asHashSet(T[] array) Returns a set backed by the given array (i.e.
static <T> Set<T>	asIdentitySet(T[] array) Returns an identity set backed by the given array (i.e.
static <T> T[]	copy(T[] src, int srcPos, T[] dest, int destPos, int length) Calls System.arraycopy(src, srcPos, dest, destPos, length) and returns the destination array.
static <T> T[]	copy(T[] src, T[] dest) Calls System.arraycopy(src, 0, dest, 0, src.length) and returns the destination array.
static <T> Iterator<T>	emptyIterator() Returns an iterator that has no elements.
static int	hashBinarySearch(Object[] array, Object key) Searches the specified array for the specified object using the binary search algorithm and object equality.
static Comparator<Object>	hashComparator() Returns a comparator that compares objects according to their hashcodes.
static <T> T[]	hashSort(T[] array) Calls Arrays.sort(Object[], Comparator) on the given array and returns it.
static int	identityBinarySearch(Object[] array, Object key) Searches the specified array for the specified object using the binary search algorithm and reference equality.
static Comparator<Object>	identityComparator() Returns a comparator that compares objects according to their identity hashcodes.
static <T> T[]	identitySort(T[] array) Calls Arrays.sort(Object[], Comparator) on the given array and returns it.
static <T,E extends T> Iterator<T>	iterate(E... items) Returns a new iterator over the given array of items.
static <T,E extends T> Iterator<T>	iterate(int start, int end, E... items) Returns a new iterator over the given array of items.
static <T> Set<T>	setDifference(Set<T> left, Set<T> right) Returns a new set that contains the asymmetric difference between the left and the right sets.

Methods inherited from class java.lang.Object

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

Method Detail

asHashSet

public static final <T> Set<T> asHashSet(T[] array)

Returns a set backed by the given array (i.e. a set that uses object equality for comparisons). The array must contain no duplicates, its elements must be sorted in the increasing order of hashcodes (as by hashSort(Object[])), and its contents must not be changed while it is in use by the returned set.

Requires:

all i, j: [0..array.length) | i < j => array[i].hashCode() <= array[j].hashCode

Returns:

an unmodifiable Set view of the given array

asIdentitySet

public static final <T> Set<T> asIdentitySet(T[] array)

Returns an identity set backed by the given array (i.e. a set that uses reference equality for comparisons). The array must contain no duplicates, its elements must be sorted in the increasing order of identity hashcodes (as by identitySort(Object[])), and its contents must not be changed while it is in use by the returned set.

Requires:

all i, j: [0..array.length) | i < j => System.identityHashCode(array[i]) <= System.identityHashCode(array[j])

Returns:

an unmodifiable identity Set view of the given array

copy

public static final <T> T[] copy(T[] src,
                                 int srcPos,
                                 T[] dest,
                                 int destPos,
                                 int length)

Calls System.arraycopy(src, srcPos, dest, destPos, length) and returns the destination array.

Ensures:

System.arraycopy(src, srcPos, dest, destPos, length)

Returns:

dest

copy

public static final <T> T[] copy(T[] src,
                                 T[] dest)

Calls System.arraycopy(src, 0, dest, 0, src.length) and returns the destination array.

Requires:

dest.length >= src.length

Ensures:

System.arraycopy(src, 0, dest, 0, src.length)

Returns:

dest

emptyIterator

public static final <T> Iterator<T> emptyIterator()

Returns an iterator that has no elements. That is, calls to hasNext will return false, and all other calls will result in a runtime exception.

Returns:

an empty iterator

hashBinarySearch

public static final int hashBinarySearch(Object[] array,
                                         Object key)

Searches the specified array for the specified object using the binary search algorithm and object equality. The array must be sorted into ascending order according to the hashcodes of its elements (as by hashSort(Object[])) prior to making this call. If it is not sorted, the results are undefined. If the array contains multiple occurences of the specified object, there is no guarantee which one will be found.

Requires:

all i, j: [0..array.length) | i < j => System.identityHashCode(array[i]) <= System.identityHashCode(array[j])

Returns:

index of the search key, if it is contained in the array; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the array: the index of the first element greater than the key, or array.length, if all elements in the array are less than the specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found.

hashComparator

public static final Comparator<Object> hashComparator()

Returns a comparator that compares objects according to their hashcodes. The null reference is considered to have a hashcode of 0.

Returns:

a comparator that compares objects according to their hashcodes.

hashSort

public static final <T> T[] hashSort(T[] array)

Calls Arrays.sort(Object[], Comparator) on the given array and returns it. The elements are sorted in the ascending order of their hashcodes.

Ensures:

java.util.Arrays.sort(array, hashComparator())

Returns:

the given array, with its elements sorted in the increasing order of hashcodes

identityBinarySearch

public static final int identityBinarySearch(Object[] array,
                                             Object key)

Searches the specified array for the specified object using the binary search algorithm and reference equality. The array must be sorted into ascending order according to the identity hashcodes of its elements (as by identitySort(Object[])) prior to making this call. If it is not sorted, the results are undefined. If the array contains multiple occurences of the specified object, there is no guarantee which one will be found.

Requires:

all i, j: [0..array.length) | i < j => array[i].hashCode() <= array[j].hashCode())

Returns:

index of the search key, if it is contained in the array; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the array: the index of the first element greater than the key, or array.length, if all elements in the array are less than the specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found.

identityComparator

public static final Comparator<Object> identityComparator()

Returns a comparator that compares objects according to their identity hashcodes.

Returns:

a comparator that compares objects according to their identity hashcodes.

identitySort

public static final <T> T[] identitySort(T[] array)

Calls Arrays.sort(Object[], Comparator) on the given array and returns it. The elements are sorted in the ascending order of their identity hashcodes.

Ensures:

java.util.Arrays.sort(array, identityComparator())

Returns:

the given array, with its elements sorted in the increasing order of identity hashcodes

iterate

@SafeVarargs
public static final <T,E extends T> Iterator<T> iterate(E... items)

Returns a new iterator over the given array of items. The iterator is backed by the given array. The contents of the array are not modified by the iterator. The effect of this method is the same as calling Iterators.iterator(0, items.length, items).

Throws:

NullPointerException - items = null

iterate

@SafeVarargs
public static final <T,E extends T> Iterator<T> iterate(int start,
                                                                     int end,
                                                                     E... items)

Returns a new iterator over the given array of items. The iterator is backed by the given array. The contents of the array are not modified by the iterator. The returned iterator enumerates the items located between indeces start, inclusive, and end, exclusive. If start < end, the elements are returned in the ascending order; otherwise, they are returned in the descending order.

Throws:

NullPointerException - items = null

IllegalArgumentException - start < end && (start < 0 || end > items.length) || start > end && (start >= items.length || end < -1)

setDifference

public static final <T> Set<T> setDifference(Set<T> left,
                                             Set<T> right)

Returns a new set that contains the asymmetric difference between the left and the right sets.

Returns:

some s: Set | s.elements = left.elements - right.elements