kodkod.util.ints
Class Ints

java.lang.Object
  extended by kodkod.util.ints.Ints

public final class Ints
extends java.lang.Object

Contains various utility methods for working with integers, IntRanges, IntSets, and SparseSequences.

The methods in this class all throw a NullPointerException if given a null reference unless otherwise specified.

Author:
Emina Torlak

Field Summary
static IntSet EMPTY_SET
          An immutable empty int set.
 
Method Summary
static IntVector asIntVector(int[] ints)
          Returns an unmodifiable IntArray backed by the given array of integers.
static IntSet asSet(int[] ints)
          Returns an IntSet that is backed by the given array of integers.
static IntSet bestSet(int max)
          Returns an implementation of the int set interface that offers the best time/space trade-off for a set that can store all elements in the half open range [0..max).
static IntSet bestSet(int min, int max)
          Returns an implementation of the int set interface that offers the best time/space trade-off for a set that can store all elements in the closed range [min..max].
static IntRange merge(IntRange r1, IntRange r2)
          Returns the smallest IntRange r that contains both r1 and r2.
static IntRange range(int min, int max)
          Returns an integer range from min, inclusive, to max, inclusive.
static IntSet rangeSet(IntRange range)
          Returns an unmodifiable IntSet that contains all the elements in the given range.
static IntSet singleton(int i)
          Returns an unmodifiable IntSet whose sole element is the given integer.
static int superFastHash(int... key)
          An implementation of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html.
static int superFastHash(int key)
          An implementation of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html.
static int superFastHash(java.lang.Object... key)
          An implementation of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html.
static int superFastHashAvalanche(int hash)
          Performs the bit avalanching step of Paul Hsieh's hashing function (http://www.azillionmonkeys.com/qed/hash.html)
static int superFastHashIncremental(int key, int hash)
          Performs the hashing step of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html.
static IntSet unmodifiableIntSet(IntSet s)
          Returns an unmodifiable view of the specified set.
static
<V> SparseSequence<V>
unmodifiableSequence(SparseSequence<V> s)
          Returns an unmodifiable view of the specified sparse sequence.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_SET

public static final IntSet EMPTY_SET
An immutable empty int set. The clone method returns the empty set itself.

Method Detail

range

public static IntRange range(int min,
                             int max)
Returns an integer range from min, inclusive, to max, inclusive.

Returns:
{ r: IntRange | r.min = min && r.max = max }
Throws:
java.lang.IllegalArgumentException - - min > max

merge

public static IntRange merge(IntRange r1,
                             IntRange r2)
Returns the smallest IntRange r that contains both r1 and r2.

Returns:
{ r: IntRange | r.contains(r1) && r.contains(r2) && no r' : IntRange - r | r'.contains(r1) && r'.contains(r2) && r'.size() < r.size() }
Throws:
java.lang.NullPointerException - - range = null

unmodifiableIntSet

public static IntSet unmodifiableIntSet(IntSet s)
Returns an unmodifiable view of the specified set. This method allows modules to provide users with "read-only" access to internal int sets. Query operations on the returned set "read through" to the specified set, and attempts to modify the returned set, whether direct or via its iterator, result in an UnsupportedOperationException. The clone() method of the returned set returns the result of calling s.clone().

Returns:
an unmodifiable view of s
Throws:
java.lang.NullPointerException - - s = null

singleton

public static IntSet singleton(int i)
Returns an unmodifiable IntSet whose sole element is the given integer. The clone method of the returned set returns the set itself.

Returns:
{s: IntSet | s.ints = i}

rangeSet

public static IntSet rangeSet(IntRange range)
Returns an unmodifiable IntSet that contains all the elements in the given range. The clone method of the returned set returns the set itself.

Returns:
{s: IntSet | s.ints = [range.min()..range.max()] }

bestSet

public static IntSet bestSet(int max)
Returns an implementation of the int set interface that offers the best time/space trade-off for a set that can store all elements in the half open range [0..max). The returned instance may or may not admit elements out of the range [0..max).

Returns:
an int set that can store at least the elements in [0..max).

bestSet

public static IntSet bestSet(int min,
                             int max)
Returns an implementation of the int set interface that offers the best time/space trade-off for a set that can store all elements in the closed range [min..max]. The returned instance may or may not admit elements out of the specified range.

Returns:
an int set that can store at least the elements in the given range.
Throws:
java.lang.IllegalArgumentException - - min > max

asSet

public static IntSet asSet(int[] ints)
Returns an IntSet that is backed by the given array of integers. The array must contain no duplicates, its elements must be sorted in the ascending order, and its contents must not be changed while it is in use by the returned set.

Returns:
an unmodifiable IntSet view of the given array
requires:
all i, j: [0..ints.length) | i < j => array[i] <= Sarray[j]

asIntVector

public static IntVector asIntVector(int[] ints)
Returns an unmodifiable IntArray backed by the given array of integers.

Returns:
an unmodifiable IntArray backed by the given array of integers.

unmodifiableSequence

public static <V> SparseSequence<V> unmodifiableSequence(SparseSequence<V> s)
Returns an unmodifiable view of the specified sparse sequence. This method allows modules to provide users with "read-only" access to internal sparse sequences. Query operations on the returned sequence "read through" to the specified sequence, and attempts to modify the returned sequence, whether direct or via its iterator, result in an UnsupportedOperationException. The clone() method of the returned sequence returns the result of calling s.clone().

Returns:
an unmodifiable view of s
Throws:
java.lang.NullPointerException - - s = null

superFastHashAvalanche

public static int superFastHashAvalanche(int hash)
Performs the bit avalanching step of Paul Hsieh's hashing function (http://www.azillionmonkeys.com/qed/hash.html)

Returns:
the bit avalanched version of the given hash value

superFastHashIncremental

public static int superFastHashIncremental(int key,
                                           int hash)
Performs the hashing step of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html. The method returns a 32 bit hash of the given integer, starting with the given initial hash. This method does not perform bit avalanching. To get the full hash, call superFastHashAvalanche(int) on the value returned by this method.

Returns:
a 32 bit hash of the given integer, based on the given hash

superFastHash

public static int superFastHash(int key)
An implementation of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html. The method returns a 32 bit hash of the given integer. This function is very fast and collision resistent; e.g. it hashes the four million integers in the range [-2000000,...-1, 1,..., 2000000] to distinct values. The initial hash is taken to be 11.

Returns:
a 32 bit hash of the given integer

superFastHash

public static int superFastHash(int... key)
An implementation of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html. The method returns a 32 bit hash of the given integers, or 0 if the array is empty. The initial hash is taken to be the number of keys.

Returns:
a 32 bit hash of the given integers

superFastHash

public static int superFastHash(java.lang.Object... key)
An implementation of Paul Hsieh's hashing function, described at http://www.azillionmonkeys.com/qed/hash.html. The method returns a 32 bit hash of the given objects' hash codes, or zero if the array is empty. Any null references in the array are taken to have 0 as their hash code value.

Returns:
a 32 bit hash of the given objects' hashCodes