kodkod.util.collections
Class Arrays

java.lang.Object
  extended by kodkod.util.collections.Arrays

public final class Arrays
extends java.lang.Object

This class provides utility methods for constructing iterators over arrays and convenience wrappers for java.util.Arrays sorting and searching procedures.

Author:
Emina Torlak

Method Summary
static
<T> java.util.Set<T>
asIdentitySet(T[] array)
          Returns an identity set backed by the given array.
static
<T> java.util.Iterator<T>
emptyIterator()
          Returns an iterator that has no elements.
static int identityBinarySearch(java.lang.Object[] array, java.lang.Object key)
          Searches the specified array for the specified object using the binary search algorithm and reference equality.
static java.util.Comparator<java.lang.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>
java.util.Iterator<T>
iterate(E... items)
          Returns a new iterator over the given array of items.
static
<T,E extends T>
java.util.Iterator<T>
iterate(int start, int end, E... items)
          Returns a new iterator over the given array of items.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

iterate

public static final <T,E extends T> java.util.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:
java.lang.NullPointerException - - items = null

iterate

public static final <T,E extends T> java.util.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:
java.lang.NullPointerException - - items = null
java.lang.IllegalArgumentException - - start < end && (start < 0 || end > items.length) || start > end && (start >= items.length || end < -1)

emptyIterator

public static final <T> java.util.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

identityComparator

public static final java.util.Comparator<java.lang.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.

Returns:
the given array, with its elements sorted in the increasing order of identity hashcodes
effects:
java.util.Arrays.sort(array, {@link #identityComparator()})

identityBinarySearch

public static final int identityBinarySearch(java.lang.Object[] array,
                                             java.lang.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.

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.
requires:
all i, j: [0..array.length) | i < j => System.identityHashCode(array[i]) <= System.identityHashCode(array[j])

asIdentitySet

public static final <T> java.util.Set<T> asIdentitySet(T[] array)
Returns an identity set backed by the given array. 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.

Returns:
an unmodifiable identity Set view of the given array
requires:
all i, j: [0..array.length) | i < j => System.identityHashCode(array[i]) <= System.identityHashCode(array[j])