Skip navigation links
AlgART Home
net.algart.math

## Class RectangularArea

• java.lang.Object
• net.algart.math.RectangularArea

• ```public class RectangularArea
extends java.lang.Object```

Rectangular real area, i.e. hyperparallelepiped in multidimensional space with real coordinates of vertices. All edges of the hyperparallelepiped are parallel to coordinate axes. In 1-dimensional case it is an equivalent of `Range` class, in 2-dimensional case it is an analog of the standard java.awt.geom.Rectangle2D class.

More precisely, the region, specified by this class, is defined by two n-dimensional points with real coordinates (`Point`), named the minimal vertex min and maximal vertex max, and consists of all such points (x0, x1, ..., xn−1), that:

min.`coord(0)`x0max.`coord(0)`,
min.`coord(1)`x1max.`coord(1)`,
...,
min.`coord(n-1)`xn−1max.`coord(n-1)`.

The min and max points are specified while creating an instance of this class and can be retrieved by `min()` and `max()` methods.

The coordinates of the minimal vertex min.`coord(i)` are never greater than the corresponding coordinates of the maximal vertex max.`coord(i)`, and all coordinates of both vertices are never Double.NaN.

All calculations in this class are performed in strictfp mode, so the result is absolutely identical on all platforms.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Since:
JDK 1.5
Version:
1.2
Author:
Daniel Alievsky
See Also:
`IRectangularArea`
• ### Method Summary

All Methods
Modifier and Type Method and Description
`boolean` `contains(Point point)`
Returns true if and only if `min`(k)<=point.`coord`(k)<=`max`(k) for all k.
`boolean` `contains(RectangularArea area)`
Returns true if and only if `min`(k)<=area.`min`(k) and area.`max`(k)<=`max`(k) for all k.
`int` `coordCount()`
Returns the number of dimensions of this rectangular area.
`java.util.Collection<RectangularArea>` ```difference(java.util.Collection<RectangularArea> results, RectangularArea area)```
Calculates the set-theoretical difference A \ B of this (A) and the passed rectangular area (B) in a form of N rectangular areas R1,R2,...,RN, the set-theoretical union of which is equal to this difference (R1R2∪...∪RN = A \ B).
`boolean` `equals(java.lang.Object obj)`
Indicates whether some other rectangular area is equal to this instance.
`RectangularArea` `expand(Point point)`
Returns the minimal rectangular area, containing this area and the given point.
`RectangularArea` `expand(RectangularArea area)`
Returns the minimal rectangular area, containing this and the passed area.
`int` `hashCode()`
Returns the hash code of this rectangular area.
`RectangularArea` `intersection(RectangularArea area)`
Returns the set-theoretical intersection A ∩ B of this (A) and the passed rectangular area (B) or null if they do not `intersect` (A ∩ B = ∅).
`boolean` `intersects(RectangularArea area)`
Returns true if and only if `min`(k)<=area.`max`(k) and area.`min`(k)<=`max`(k) for all k.
`Point` `max()`
Returns the maximal vertex of this rectangular area: the point with maximal coordinates, belonging to this area.
`double` `max(int coordIndex)`
`Point` `min()`
Returns the minimal vertex of this rectangular area: the point with minimal coordinates, belonging to this area.
`double` `min(int coordIndex)`
`boolean` `overlaps(RectangularArea area)`
Returns true if and only if `min`(k)<area.`max`(k) and area.`min`(k)<`max`(k) for all k.
`double` `parallelDistance(double... coordinates)`
Equivalent to `parallelDistance`(`Point.valueOf`(coordinates)), but works faster because does not require to create an instance of `Point` class.
`double` ```parallelDistance(double x, double y)```
Equivalent to `parallelDistance`(`Point.valueOf`(x, y)), but works faster because does not require to allocate any objects.
`double` ```parallelDistance(double x, double y, double z)```
Equivalent to `parallelDistance`(`Point.valueOf`(x, y, z)), but works faster because does not require to allocate any objects.
`double` `parallelDistance(Point point)`
Returns the parallel distance from the given point to this rectangular area.
`Range` `range(int coordIndex)`
`Range[]` `ranges()`
Returns the projections of this rectangular area to all axes.
`RectangularArea` `shift(Point vector)`
Shifts this rectangular area by the specified vector and returns the shifted area.
`RectangularArea` `shiftBack(Point vector)`
Shifts this rectangular area by vector.`symmetric()` and returns the shifted area.
`Point` `size()`
Returns all sizes of this rectangular area in a form of `Point`.
`double` `size(int coordIndex)`
Returns `max`(coordIndex) - `min`(coordIndex).
`double[]` `sizes()`
Returns the sizes of this rectangular area along all dimensions.
`static java.util.Queue<RectangularArea>` ```subtractCollection(java.util.Queue<RectangularArea> fromWhatToSubtract, java.util.Collection<RectangularArea> whatToSubtract)```
Calculates the set-theoretical difference A \ B of the set-theoretical union A of all elements of the collection fromWhatToSubtract and the set-theoretical union B of all elements of the collection whatToSubtract, in a form of a union of N rectangular areas, and replaces the old content of fromWhatToSubtract with the resulting N areas.
`static java.util.Queue<RectangularArea>` ```subtractCollection(java.util.Queue<RectangularArea> fromWhatToSubtract, RectangularArea... whatToSubtract)```
Equivalent to `subtractCollection`(fromWhatToSubtract, java.util.Arrays.asList(whatToSubtract)).
`IRectangularArea` `toIntegerRectangularArea()`
Equivalent to `IRectangularArea.valueOf`(thisInstance), with the only difference that IllegalStateException is thrown instead of IllegalArgumentException for unallowed rectangular area.
`IRectangularArea` `toRoundedRectangularArea()`
Equivalent to `IRectangularArea.roundOf`(thisInstance), with the only difference that IllegalStateException is thrown instead of IllegalArgumentException for unallowed rectangular area.
`java.lang.String` `toString()`
Returns a brief string description of this object.
`static RectangularArea` ```valueOf(double minX, double minY, double maxX, double maxY)```
Returns a 2-dimensional rectangle with the given minimal and maximal vertex.
`static RectangularArea` ```valueOf(double minX, double minY, double minZ, double maxX, double maxY, double maxZ)```
Returns a 3-dimensional parallelepiped with the given minimal and maximal vertex.
`static RectangularArea` `valueOf(IRectangularArea iArea)`
Returns a new rectangular area with the same coordinates as the given area.
`static RectangularArea` ```valueOf(Point min, Point max)```
Returns an instance of this class with the given minimal vertex min and maximal vertex max.
`static RectangularArea` `valueOf(Range... coordRanges)`
Returns the Cartesian product of the specified coordinate ranges.
`double` `volume()`
Returns the volume of this rectangular area: the product of all sizes returned by `sizes()` method.
• ### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`
• ### Method Detail

• #### valueOf

```public static RectangularArea valueOf(Point min,
Point max)```
Returns an instance of this class with the given minimal vertex min and maximal vertex max. See the `comments to this class` for more details.
Parameters:
`min` - the minimal vertex, inclusive.
`max` - the maximal vertex, inclusive.
Returns:
the new rectangular area "between" these vertices.
Throws:
`java.lang.NullPointerException` - if one of arguments is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in min and max points are different, or if, for some i, min.`coord`(i) > max.`coord`(i), or if one of these coordinates is Double.NaN.
• #### valueOf

`public static RectangularArea valueOf(Range... coordRanges)`
Returns the Cartesian product of the specified coordinate ranges. More precisely, return an n-dimensional `rectangular area` with the minimal vertex min and maximal vertex max, where n=coordRanges.length, min.`coord(i)`=coordRanges[i].`min()`, max.`coord(i)`=coordRanges[i].`max()`. See the `comments to this class` for more details.
Parameters:
`coordRanges` - the coordinate ranges.
Returns:
the Cartesian product of the specified coordinate ranges.
Throws:
`java.lang.NullPointerException` - if the argument is null or if one of specified coordRanges is null.
`java.lang.IllegalArgumentException` - if the passed array is empty (no ranges are passed).
• #### valueOf

```public static RectangularArea valueOf(double minX,
double minY,
double maxX,
double maxY)```
Returns a 2-dimensional rectangle with the given minimal and maximal vertex. Equivalent to
``` `valueOf`(
`Point.valueOf`(minX, minY),
`Point.valueOf`(maxX, maxY));
```
Parameters:
`minX` - the minimal x-coordinate, inclusive.
`minY` - the minimal y-coordinate, inclusive.
`maxX` - the maximal x-coordinate, inclusive.
`maxY` - the maximal y-coordinate, inclusive.
Returns:
the new 2-dimensional rectangle.
Throws:
`java.lang.IllegalArgumentException` - in the same situations as `valueOf(Point, Point)` method.
• #### valueOf

```public static RectangularArea valueOf(double minX,
double minY,
double minZ,
double maxX,
double maxY,
double maxZ)```
Returns a 3-dimensional parallelepiped with the given minimal and maximal vertex. Equivalent to
``` `valueOf`(
`Point.valueOf`(minX, minY, minZ),
`Point.valueOf`(maxX, maxY, maxZ));
```
Parameters:
`minX` - the minimal x-coordinate, inclusive.
`minY` - the minimal y-coordinate, inclusive.
`minZ` - the minimal z-coordinate, inclusive.
`maxX` - the maximal x-coordinate, inclusive.
`maxY` - the maximal y-coordinate, inclusive.
`maxZ` - the maximal z-coordinate, inclusive.
Returns:
the new 3-dimensional parallelepiped.
Throws:
`java.lang.IllegalArgumentException` - in the same situations as `valueOf(Point, Point)` method.
• #### valueOf

`public static RectangularArea valueOf(IRectangularArea iArea)`
Returns a new rectangular area with the same coordinates as the given area. All long coordinates of the passed area are converted to double coordinates of the returned area by standard Java typecast (double)longValue. Equivalent to `valueOf`(`Point.valueOf`(iArea.`min()`), `Point.valueOf`(iArea.`max()`)).
Parameters:
`iArea` - the integer rectangular area.
Returns:
the real rectangular area with same coordinates.
Throws:
`java.lang.NullPointerException` - if the passed area is null.
• #### min

`public Point min()`
Returns the minimal vertex of this rectangular area: the point with minimal coordinates, belonging to this area. See the `comments to this class` for more details.
Returns:
the minimal vertex of this rectangular area.
• #### max

`public Point max()`
Returns the maximal vertex of this rectangular area: the point with maximal coordinates, belonging to this area. See the `comments to this class` for more details.
Returns:
the maximal vertex of this rectangular area.
• #### sizes

`public double[] sizes()`
Returns the sizes of this rectangular area along all dimensions. The returned array consists of `coordCount()` elements, and the element #k contains `size`(k).
Returns:
the sizes of this rectangular area along all dimensions.
• #### volume

`public double volume()`
Returns the volume of this rectangular area: the product of all sizes returned by `sizes()` method.
Returns:
the multidimensional volume of this rectangular area (usual area in 2-dimensional case).
• #### ranges

`public Range[] ranges()`
Returns the projections of this rectangular area to all axes. The returned array consists of `coordCount()` elements, and the element #k contains `range`(k).
Returns:
the projections of this rectangular area to all axes.
• #### intersects

`public boolean intersects(RectangularArea area)`
Returns true if and only if `min`(k)<=area.`max`(k) and area.`min`(k)<=`max`(k) for all k.
Parameters:
`area` - the checked rectangular area.
Returns:
true if the checked rectangular area overlaps with this area, maybe in boundary points only.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if area.`coordCount()` is not equal to the `number of dimensions` of this instance.
• #### intersection

`public RectangularArea intersection(RectangularArea area)`
Returns the set-theoretical intersection A ∩ B of this (A) and the passed rectangular area (B) or null if they do not `intersect` (A ∩ B = ∅). Equivalent to
```thisInstance.`intersects`(area) ? `RectangularArea.valueOf`(
thisInstance.`min()`.`max`(area.`min()`),
thisInstance.`max()`.`min`(area.`max()`)) :
null```
.
Parameters:
`area` - the second rectangular area.
Returns:
intersection of this and the second rectangular area or null if they do not intersect.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if area.`coordCount()` is not equal to the `number of dimensions` of this instance.
• #### difference

```public java.util.Collection<RectangularArea> difference(java.util.Collection<RectangularArea> results,
RectangularArea area)```
Calculates the set-theoretical difference A \ B of this (A) and the passed rectangular area (B) in a form of N rectangular areas R1,R2,...,RN, the set-theoretical union of which is equal to this difference (R1R2∪...∪RN = A \ B). The resulting areas R1,R2,...,RN are added into the collection results by Collection.add(...) method. So, the collection results must be not-null and support adding elements (usually it is List or Queue).

It is possible that the difference is empty (A \ B = ∅), i.e. this area A is a subset of the passed one B. In this case, this method does nothing.

It is possible that the difference is equal to this area (A \ B = A), i.e. this area A does not intersect the passed one B. In this case, this method is equivalent to results.add(thisInstance) call.

In other cases, there is more than 1 way to represent the resulting difference in a form of union of several rectangular areas R1,R2,...,RN. The precise way, how this method forms this set of rectangular areas Ri, is not documented, but this method tries to minimize the number N of such areas. In any case, there is a guarantee that N≤2*`coordCount()`.

Parameters:
`results` - the collection to store results.
`area` - the area B, subtracted from this area A.
Returns:
a reference to the results argument.
Throws:
`java.lang.NullPointerException` - if result or area argument is null.
`java.lang.IllegalArgumentException` - if area.`coordCount()` is not equal to the `number of dimensions` of this instance.
See Also:
`subtractCollection(java.util.Queue, java.util.Collection)`
• #### subtractCollection

```public static java.util.Queue<RectangularArea> subtractCollection(java.util.Queue<RectangularArea> fromWhatToSubtract,
java.util.Collection<RectangularArea> whatToSubtract)```
Calculates the set-theoretical difference A \ B of the set-theoretical union A of all elements of the collection fromWhatToSubtract and the set-theoretical union B of all elements of the collection whatToSubtract, in a form of a union of N rectangular areas, and replaces the old content of fromWhatToSubtract with the resulting N areas.

More precisely, this method is equivalent to the following loop:

``` for (RectangularArea area : whatToSubtract) {
for (int i = 0, n = fromWhatToSubtract.size(); i < n; i++) {
RectangularArea minuend = fromWhatToSubtract.poll();
minuend.`difference`(fromWhatToSubtract, area);
}
if (fromWhatToSubtract.isEmpty()) {
break;
}
}
```

Note: if some exception occurs while execution of the listed loop (for example, some elements of the collections are null or have different number of dimensions), the fromWhatToSubtract stays partially modified. In other words, this method is non-atomic regarding failures.

Parameters:
`fromWhatToSubtract` - the minuend A, which will be replaced with A \ B.
`whatToSubtract` - the subtrahend B.
Returns:
a reference to fromWhatToSubtract argument, which will contain the difference A \ B.
Throws:
`java.lang.NullPointerException` - if fromWhatToSubtract or whatToSubtract argument is null or if one of their elements it null.
`java.lang.IllegalArgumentException` - if some of elements of the passed collections have different `coordCount()`.
See Also:
`subtractCollection(java.util.Queue, RectangularArea...)`
• #### subtractCollection

```public static java.util.Queue<RectangularArea> subtractCollection(java.util.Queue<RectangularArea> fromWhatToSubtract,
RectangularArea... whatToSubtract)```
Equivalent to `subtractCollection`(fromWhatToSubtract, java.util.Arrays.asList(whatToSubtract)).
Parameters:
`fromWhatToSubtract` - the minuend A, which will be replaced with A \ B.
`whatToSubtract` - the subtrahend B.
Returns:
a reference to fromWhatToSubtract argument, which will contain the difference A \ B.
Throws:
`java.lang.NullPointerException` - if fromWhatToSubtract or whatToSubtract argument is null or if one of their elements it null.
`java.lang.IllegalArgumentException` - if some of elements of the passed collection and array have different `coordCount()`.
• #### expand

`public RectangularArea expand(RectangularArea area)`
Returns the minimal rectangular area, containing this and the passed area. Equivalent to
````RectangularArea.valueOf`(
thisInstance.`min()`.`min`(area.`min()`),
thisInstance.`max()`.`max`(area.`max()`))```
.
Parameters:
`area` - the second rectangular area.
Returns:
the minimal rectangular area, containing this and the passed area.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if area.`coordCount()` is not equal to the `number of dimensions` of this instance.
• #### parallelDistance

`public double parallelDistance(Point point)`
Returns the parallel distance from the given point to this rectangular area. The parallel distance is a usual distance, with plus or minus sign, from the point to some of hyperplanes, containing the hyperfacets of this hyperparallelepiped, chosen so that:
1. the parallel distance is zero at the hyperfacets, negative inside the rectangular area and positive outside it;
2. for any constant c, the set of all such points, that the parallel distance from them to this rectangular area ≤c, is also hyperparallelepiped (rectangular area) wich hyperfacets, parallel to the the coordinate hyperplanes, or an empty set if c<c0, where c0 is the (negative) parallel distance from the geometrical center of this hyperparallelepiped.

Formally, let p is any point with coordinates p0, p1, ..., pn−1, li = `min`(i), ri = `max`(i), di = max(lipi, piri). Note that di is positive if pi<li or pi>ri and negative if pi is inside li..ri range. The parallel distance from the point p to this rectangular area is defined as maximal value from all di: max(d0, d1, ..., dn−1).

Parameters:
`point` - some point.
Returns:
the parallel distance from this point to this rectangular area.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if point.`coordCount()` is not equal to the `number of dimensions` of this instance.
• #### parallelDistance

`public double parallelDistance(double... coordinates)`
Equivalent to `parallelDistance`(`Point.valueOf`(coordinates)), but works faster because does not require to create an instance of `Point` class.
Parameters:
`coordinates` - coordinates of some point.
Returns:
the parallel distance from this point to this rectangular area.
Throws:
`java.lang.NullPointerException` - if coordinates argument is null.
`java.lang.IllegalArgumentException` - if coordinates.length is not equal to the `number of dimensions` of this instance.
• #### parallelDistance

```public double parallelDistance(double x,
double y)```
Equivalent to `parallelDistance`(`Point.valueOf`(x, y)), but works faster because does not require to allocate any objects. Works only for 2-dimensional rectangular areas, in other cases throws IllegalArgumentException.
Parameters:
`x` - the 1st coordinate of some point.
`y` - the 2nd coordinate of some point.
Returns:
the parallel distance from this point to this rectangular area.
Throws:
`java.lang.IllegalArgumentException` - if coordinates.length!=2 .
• #### parallelDistance

```public double parallelDistance(double x,
double y,
double z)```
Equivalent to `parallelDistance`(`Point.valueOf`(x, y, z)), but works faster because does not require to allocate any objects. Works only for 3-dimensional rectangular areas, in other cases throws IllegalArgumentException.
Parameters:
`x` - the 1st coordinate of some point.
`y` - the 2nd coordinate of some point.
`z` - the 3rd coordinate of some point.
Returns:
the parallel distance from this point to this rectangular area.
Throws:
`java.lang.IllegalArgumentException` - if coordinates.length!=2 .
• #### shift

`public RectangularArea shift(Point vector)`
Shifts this rectangular area by the specified vector and returns the shifted area. Equivalent to
``valueOf`(thisInstance.`min()`.`add`(vector), thisInstance.`max()`.`add`(vector))`
Parameters:
`vector` - the vector which is added to all vertices of this area.
Returns:
the shifted area.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if vector.`coordCount()` is not equal to the `number of dimensions` of this instance.
• #### shiftBack

`public RectangularArea shiftBack(Point vector)`
Shifts this rectangular area by vector.`symmetric()` and returns the shifted area. Equivalent to
``valueOf`(thisInstance.`min()`.`subtract`(vector), thisInstance.`max()`.`subtract`(vector))`
Parameters:
`vector` - the vector which is subtracted from all vertices of this area.
Returns:
the shifted area.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if vector.`coordCount()` is not equal to the `number of dimensions` of this instance.
• #### toIntegerRectangularArea

`public IRectangularArea toIntegerRectangularArea()`
Equivalent to `IRectangularArea.valueOf`(thisInstance), with the only difference that IllegalStateException is thrown instead of IllegalArgumentException for unallowed rectangular area.
Returns:
the integer rectangular area with same (cast) coordinates.
Throws:
`java.lang.IllegalStateException` - in the same situation when `IRectangularArea.valueOf(RectangularArea)` method throws IllegalArgumentException.
• #### toRoundedRectangularArea

`public IRectangularArea toRoundedRectangularArea()`
Equivalent to `IRectangularArea.roundOf`(thisInstance), with the only difference that IllegalStateException is thrown instead of IllegalArgumentException for unallowed rectangular area.
Returns:
the integer rectangular area with same (rounded) coordinates.
Throws:
`java.lang.IllegalStateException` - in the same situation when `IRectangularArea.roundOf(RectangularArea)` method throws IllegalArgumentException.
• #### toString

`public java.lang.String toString()`
Returns a brief string description of this object.

The result of this method may depend on implementation and usually contains information about all coordinates ranges between the minimum and maximum vertices of this area.

Overrides:
`toString` in class `java.lang.Object`
Returns:
a brief string description of this object.
• #### hashCode

`public int hashCode()`
Returns the hash code of this rectangular area.
Overrides:
`hashCode` in class `java.lang.Object`
Returns:
the hash code of this rectangular area.
• #### equals

`public boolean equals(java.lang.Object obj)`
Indicates whether some other rectangular area is equal to this instance. Returns true if and only if obj instanceof RectangularArea, ((RectangularArea)obj).min().equals(this.min()) and ((RectangularArea)obj).max().equals(this.max()).
Overrides:
`equals` in class `java.lang.Object`
Parameters:
`obj` - the object to be compared for equality with this instance.
Returns:
true if the specified object is a rectangular area equal to this one.