kodkod.engine.bool
Class Dimensions

java.lang.Object
  extended by kodkod.engine.bool.Dimensions

public abstract class Dimensions
extends java.lang.Object

Stores information about the size of a matrix. Specifically, for an n-dimensional matrix n, a Dimensions object is abstractly a vector consisting of n integers; the ith integer in the vector represents the size of the ith dimension of a matrix.

Author:
Emina Torlak
invariant:
n > 0
specfield:
n: int
dimensions: [0..n) -> one int
capacity: dimensions[0] x ... x dimensions[n-1]

Method Summary
 int capacity()
          Returns the capacity of this.
 int[] convert(int index)
          Converts an integer index into a matrix with these dimensions into a vector index.
 int convert(int[] vectorIndex)
          Converts the first this.n positions of the given vector index into an integer index.
 void convert(int index, int[] vectorIndex)
          Converts an integer index into a matrix with these dimensions into a vector index, and stores the result in the provided array.
 Dimensions cross(Dimensions dim)
          Returns the dimensions of a matrix that would result from taking the cross product of a matrix of dimensions given by this and a matrix whose dimensions are specified by dim.
abstract  int dimension(int i)
          Returns the size of the ith dimensions
 Dimensions dot(Dimensions dim)
          Returns the dimensions of a matrix that would result from multiplying a matrix of dimensions given by this by a matrix whose dimensions are specified by dim.
abstract  boolean isSquare()
          Returns true if this represents the dimensions of a square matrix; otherwise returns false.
abstract  int numDimensions()
          Returns the number of dimensions in this Dimensions object.
static Dimensions rectangular(int[] dimensions)
          Constructs a new Dimensions object with the given dimensions.
static Dimensions square(int size, int n)
          Returns a new Dimensions object with n dimensions, each of which has the specified size.
 java.lang.String toString()
           
abstract  Dimensions transpose()
          Returns the transpose of these dimensions.
 boolean validate(int index)
          Returns true if index is a valid flat index for a matrix with these dimensions; otherwise returns false.
 boolean validate(int[] index)
          Returns true if index is a valid vector index for a matrix with these dimensions; otherwise returns false.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

square

public static Dimensions square(int size,
                                int n)
Returns a new Dimensions object with n dimensions, each of which has the specified size.

Returns:
{d: Dimensions | d.n = n && d.dimensions[int] = size }
Throws:
java.lang.IllegalArgumentException - - n < 1 || size < 1

rectangular

public static Dimensions rectangular(int[] dimensions)
Constructs a new Dimensions object with the given dimensions.

Returns:
{d: Dimensions | d.n = dimensions.length && d.dimensions = dimensions }
Throws:
java.lang.NullPointerException - - dimensions = null
java.lang.IllegalArgumentException - - dimensions.length = 0 || some i: [0..dimensions.n) | dimensions[i] < 1

capacity

public final int capacity()
Returns the capacity of this.

Returns:
this.capacity

dimension

public abstract int dimension(int i)
Returns the size of the ith dimensions

Returns:
this.dimensions[i]
Throws:
java.lang.ArrayIndexOutOfBoundsException - - i < 0 || i >= this.capacity

numDimensions

public abstract int numDimensions()
Returns the number of dimensions in this Dimensions object.

Returns:
this.n

isSquare

public abstract boolean isSquare()
Returns true if this represents the dimensions of a square matrix; otherwise returns false.

Returns:
all i, j: [0..capacity) | this.dimensions[i] = this.dimensions[j]

dot

public final Dimensions dot(Dimensions dim)
Returns the dimensions of a matrix that would result from multiplying a matrix of dimensions given by this by a matrix whose dimensions are specified by dim.

Returns:
{ d: Dimensions | d.n = this.n + dim.n - 2 && (all i: [0..this.n-1) | d.dimensions[i] = this.dimensions[i]) && (all i: [this.n-1..d.n) | d.dimensions[i] = dim.dimensions[i-this.n+1])}
Throws:
java.lang.IllegalArgumentException - - this.n + dim.n < 3 || this.dimensions[n-1] != dim.dimensions[0]

cross

public final Dimensions cross(Dimensions dim)
Returns the dimensions of a matrix that would result from taking the cross product of a matrix of dimensions given by this and a matrix whose dimensions are specified by dim.

Returns:
{ d: Dimensions | d.n = this.n + dim.n && (all i: [0..this.n) | d.dimensions[i] = this.dimensions[i]) && (all i: [this.n..d.n) | d.dimensions[i] = dim.dimensions[i-this.n])}

transpose

public abstract Dimensions transpose()
Returns the transpose of these dimensions.

Returns:
{ d: Dimensions | d.n = 2 && d.dimensions[0] = this.dimensions[1] && d.dimensions[1] = this.dimensions[0] }
Throws:
java.lang.UnsupportedOperationException - - this.n != 2

validate

public final boolean validate(int index)
Returns true if index is a valid flat index for a matrix with these dimensions; otherwise returns false.

Returns:
0 <= i < this.capacity

validate

public final boolean validate(int[] index)
Returns true if index is a valid vector index for a matrix with these dimensions; otherwise returns false.

Returns:
index.length = n && (all i: [0..this.capacity) | 0 <= index[i] < this.dimensions[i])
Throws:
java.lang.NullPointerException - - index = null

convert

public final int[] convert(int index)
Converts an integer index into a matrix with these dimensions into a vector index. The effect of this method is the same as calling this.convert(index, new int[this.numDimensions()]).

Returns:
an array of ints that represents a vector index corresponding to the specified integer index into a this.dimensions[0]x...xthis.dimensions[n-1] matrix
Throws:
java.lang.IndexOutOfBoundsException - - !validate(index)

convert

public final void convert(int index,
                          int[] vectorIndex)
Converts an integer index into a matrix with these dimensions into a vector index, and stores the result in the provided array. This method requires that the array argument have at least this.n cells, which are used to store the vector representation of the given index. The contents of the cells of vectorIndex beyond the first this.n cells are left unchanged.

Throws:
java.lang.NullPointerException - - vectorIndex = null
java.lang.IllegalArgumentException - - vectorIndex.length < this.numDimensions
java.lang.IndexOutOfBoundsException - - !validate(index)
effects:
the first this.numDimensions entries of vectorIndex contain the vector index representation of the specified integer index into a this.dimensions[0]x...xthis.dimensions[n-1] matrix
requires:
vectorIndex.length <= this.n

convert

public final int convert(int[] vectorIndex)
Converts the first this.n positions of the given vector index into an integer index.

Returns:
an integer index corresponding to the first this.numDimensions positions of the specified vector index into a this.dimensions[0]x...xthis.dimensions[n-1] matrix
Throws:
java.lang.NullPointerException - - index == null
java.lang.IllegalArgumentException - - index.length < this.n
java.lang.IndexOutOfBoundsException - - some i: [0..n) | index[i] < 0 || index[i] >= this.dimensions[i]

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
See Also:
Object.toString()