JaCoP.constraints.geost
Class DBox

java.lang.Object
  JaCoP.constraints.geost.DBox

public class DBox
extends java.lang.Object

Author:

Marc-Olivier Fleury and Radoslaw Szymanek

Field Summary

static SimpleArrayList<SimpleArrayList<DBox>>	freeBoxes static store of available boxes, accessible by dimension.
int[]	length It specifies for each dimension the length of dbox in that dimension.
int[]	origin It specifies point in n-dimensional space where the dbox originates from.
static SimpleArrayList<DBox>	transientInstances TODO, finish the comment.
static java.lang.String[]	xmlAttributes It specifies the arguments required to be saved by an XML format as well as the constructor being called to recreate an object from an XML format.

Constructor Summary

DBox(int[] origin, int[] length)
constructs a new Box.

Method Summary

int	area() It computes the area in 2D case or volume in 3D case.
static DBox	boundingBox(java.util.Collection<DBox> boxes) computes the bounding box of the given collection of boxes
java.lang.String	checkInvariants() It checks whether the DBox is consistent.
boolean	containsPoint(int[] pointCoordinates) It checks if this DBox contains the point as specified by an array of coordinates.
DBox	copyInto(DBox box) It copies this DBox into given DBox.
static void	dispatchBox(DBox unusedBox) It allows the system to reuse the given box by placing it into the pool of allocated boxes.
boolean	equals(java.lang.Object obj)
static DBox	getAllocatedInstance(int dimension) It returns an instance of DBox of the corresponding dimension, using a previously allocated one if possible
int	hashCode()
DBox	intersectWith(DBox other) It intersects this DBox with the given DBox.
DBox	intersectWith(DBox other, int[] otherOffset) It intersects this DBox with the given DBox, but the other DBox is shifted by the specified offset.
DBox	intersectWith(int[] offset, DBox other, int[] otherOffset) It intersects this DBox with a view of the given DBox that was shifted according to the given offset.
static DBox	newBox(int dimension) It returns an usable box, reusing a box from the pool if possible.
static java.lang.String	poolStatus() It provides a string representation of the DBoxes which are present in the DBox pool.
java.util.Collection<DBox>	subtract(DBox hole, java.util.Collection<DBox> difference) computes the difference between this box and the given box.
java.util.Collection<DBox>	subtractAll(java.util.Collection<DBox> others, java.util.Collection<DBox> result) It computes the result of a subtraction from this box of all the boxes given.
static java.util.Collection<DBox>	subtractAll(java.util.Collection<DBox> source, java.util.Collection<DBox> holes, java.util.Collection<DBox> result) It computes the result of a subtraction from the given collection of boxes of all the boxes given in the subtracting collection.
static void	supportDimension(int dimension) It makes sure that there is a slot of the given dimension in the slot.
java.lang.String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

transientInstances

public static final SimpleArrayList<DBox> transientInstances

TODO, finish the comment. static instance that can be used to avoid allocating new resources each time a DBox needs to be returned; modify the static instance using getAllocatedInstance(dim) instead

freeBoxes

public static final SimpleArrayList<SimpleArrayList<DBox>> freeBoxes

static store of available boxes, accessible by dimension. This makes it possible to reuse previously used boxes that are not used anymore. The user should use dispatchBox() to get rid of a box that is not needed anymore, and newBox(dimension) to get a new one.

origin

public final int[] origin

It specifies point in n-dimensional space where the dbox originates from.

length

public final int[] length

It specifies for each dimension the length of dbox in that dimension.

xmlAttributes

public static java.lang.String[] xmlAttributes

It specifies the arguments required to be saved by an XML format as well as the constructor being called to recreate an object from an XML format.

Constructor Detail

DBox

public DBox(int[] origin,
            int[] length)

constructs a new Box. The parameter arrays are not copied.

Parameters:

origin - it specifies the origin of the DBox in the n-dimensional space.

length - it specifies the length of the Dbox in the n-dimensional space.

Method Detail

supportDimension

public static final void supportDimension(int dimension)

It makes sure that there is a slot of the given dimension in the slot. It has to be called at least once before using newBox() and dispatchBox().

Parameters:

dimension -

checkInvariants

public java.lang.String checkInvariants()

It checks whether the DBox is consistent.

Returns:

It returns the string description of the problem, or null if no problem with data structure consistency encountered.

dispatchBox

public static final void dispatchBox(DBox unusedBox)

It allows the system to reuse the given box by placing it into the pool of allocated boxes. After calling this function, the caller must not keep any reference to the box, as the box may be arbitrary changed by any future owner.

Parameters:

unusedBox - the not used DBox which is being recycled.

newBox

public static final DBox newBox(int dimension)

It returns an usable box, reusing a box from the pool if possible. A DBox that is not used anymore should be put back into the pool using dispatchBox.

Parameters:

dimension - it specifies number of dimensions of a requested box

Returns:

It returns DBox with the specified dimension. Later on, when box is no longer needed it should be dispatched back.

getAllocatedInstance

public static final DBox getAllocatedInstance(int dimension)

It returns an instance of DBox of the corresponding dimension, using a previously allocated one if possible

Parameters:

dimension -

Returns:

it returns a preallocated DBox of a given dimensions.

poolStatus

public static java.lang.String poolStatus()

It provides a string representation of the DBoxes which are present in the DBox pool.

Returns:

string representation of the pool of DBoxes.

containsPoint

public boolean containsPoint(int[] pointCoordinates)

It checks if this DBox contains the point as specified by an array of coordinates.

Parameters:

pointCoordinates - it specifies the point coordinates.

Returns:

true if the point is inside DBox.

intersectWith

public DBox intersectWith(DBox other)

It intersects this DBox with the given DBox. For efficiency reasons, the DBox returned is the static instance; if it needs to be stored, a copy has to be made using clone().

Parameters:

other - the DBox to intersect this one with

Returns:

null if the intersection is empty, or a reference to a static DBox corresponding to the intersection. The result must be cloned if its scope is not local.

intersectWith

public DBox intersectWith(DBox other,
                          int[] otherOffset)

It intersects this DBox with the given DBox, but the other DBox is shifted by the specified offset. For efficiency reasons, the DBox returned is the static instance; if it needs to be stored, a copy has to be made using clone().

Parameters:

other - DBox with which the intersection is computed.

otherOffset - the offset

Returns:

null if the intersection is empty, or a reference to a static DBox corresponding to the intersection. The result must be cloned if its scope is not local.

intersectWith

public DBox intersectWith(int[] offset,
                          DBox other,
                          int[] otherOffset)

It intersects this DBox with a view of the given DBox that was shifted according to the given offset. If the intersection is empty, returns null. For efficiency reasons, the DBox returned is the static instance; if it needs to be stored, a copy has to be made using clone().

Parameters:

offset - the offset to apply to this box before intersecting

other - the DBox to intersect this one with

otherOffset - the offset to apply to the other DBox before intersecting

Returns:

null if the intersection is empty, or a reference to a static DBox corresponding to the intersection. Clone if its scope is not local.

subtract

public java.util.Collection<DBox> subtract(DBox hole,
                                           java.util.Collection<DBox> difference)

computes the difference between this box and the given box. The difference is returned under the form of a collection of boxes. NOTE: the collection of DBoxes returned is not minimal (in some cases, some boxes can be merged) if needed, implement a version that can take a lexical order as argument, to allow brute force search or learning of the best decomposition

Parameters:

hole - the box to subtract this box with

difference - the collection of boxes corresponding to the remaining area

Returns:

the computed difference, which is the difference paramter after the call (this is for ease of use only)

boundingBox

public static DBox boundingBox(java.util.Collection<DBox> boxes)

computes the bounding box of the given collection of boxes

Parameters:

boxes -

Returns:

a temporary DBox that represents the bounding box of the given boxes. clone it if you need to reuse it.

subtractAll

public static java.util.Collection<DBox> subtractAll(java.util.Collection<DBox> source,
                                                     java.util.Collection<DBox> holes,
                                                     java.util.Collection<DBox> result)

It computes the result of a subtraction from the given collection of boxes of all the boxes given in the subtracting collection. The collection used to store the result is given to avoid allocating a new set of boxes each time the function is called. However, for ease of use, it is also returned (after the call, the result argument is equal to the returned value).

Parameters:

source - the collection of boxes to subtract from

holes - the boxes to subtract from the source boxes

result - the collection to store the resulting boxes into

Returns:

the result argument, for ease of use

subtractAll

public java.util.Collection<DBox> subtractAll(java.util.Collection<DBox> others,
                                              java.util.Collection<DBox> result)

It computes the result of a subtraction from this box of all the boxes given. The collection used to store the result is given to avoid allocating a new set of boxes each time the function is called. However, for ease of use, it is also returned (after the call, the result argument is equal to the returned value)

Parameters:

others - the boxes to subtract from this box

result - the collection to store the resulting boxes into

Returns:

the result argument, for ease of use

area

public int area()

It computes the area in 2D case or volume in 3D case.

Returns:

the area/volume of the DBox.

copyInto

public final DBox copyInto(DBox box)

It copies this DBox into given DBox.

Parameters:

box - the DBox to copy this DBox into

Returns:

for convenience reasons, returns the copied DBox (same as the argument)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object