AlgART Home
net.algart.math

## Class IRectangularArea

• java.lang.Object
• net.algart.math.IRectangularArea
• ### Method Summary

Methods
Modifier and Type Method and Description
`boolean` `contains(IPoint point)`
Returns true if and only if `min`(k)<=point.`coord`(k)<=`max`(k) for all k.
`boolean` `contains(IRectangularArea 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<IRectangularArea>` ```difference(java.util.Collection<IRectangularArea> results, IRectangularArea 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.
`IRectangularArea` `expand(IPoint point)`
Returns the minimal rectangular area, containing this area and the given point.
`IRectangularArea` `expand(IRectangularArea area)`
Returns the minimal rectangular area, containing this and the passed area.
`int` `hashCode()`
Returns the hash code of this rectangular area.
`IRectangularArea` `intersection(IRectangularArea 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(IRectangularArea area)`
Returns true if and only if `min`(k)<=area.`max`(k) and area.`min`(k)<=`max`(k) for all k.
`IPoint` `max()`
Returns the maximal vertex of this rectangular area: the point with maximal coordinates, belonging to this area.
`long` `max(int coordIndex)`
`IPoint` `min()`
Returns the minimal vertex of this rectangular area: the point with minimal coordinates, belonging to this area.
`long` `min(int coordIndex)`
`long` `parallelDistance(IPoint point)`
Returns the parallel distance from the given point to this rectangular area.
`long` `parallelDistance(long... coordinates)`
Equivalent to `parallelDistance`(`IPoint.valueOf`(coordinates)), but works faster because does not require to create an instance of `IPoint` class.
`long` ```parallelDistance(long x, long y)```
Equivalent to `parallelDistance`(`IPoint.valueOf`(x, y)), but works faster because does not require to allocate any objects.
`long` ```parallelDistance(long x, long y, long z)```
Equivalent to `parallelDistance`(`IPoint.valueOf`(x, y, z)), but works faster because does not require to allocate any objects.
`IRange` `range(int coordIndex)`
`IRange[]` `ranges()`
Returns the projections of this rectangular area to all axes.
`static IRectangularArea` `roundOf(RectangularArea area)`
Returns a new rectangular area with the same coordinates as the given area.
`IRectangularArea` `shift(IPoint vector)`
Shifts this rectangular area by the specified vector and returns the shifted area.
`IPoint` `size()`
Returns all sizes of this rectangular area in a form of `IPoint`.
`long` `size(int coordIndex)`
Returns `max`(coordIndex) - `min`(coordIndex) + 1.
`long[]` `sizes()`
Returns the sizes of this rectangular area along all dimensions.
`static java.util.Queue<IRectangularArea>` ```subtractCollection(java.util.Queue<IRectangularArea> fromWhatToSubtract, java.util.Collection<IRectangularArea> 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<IRectangularArea>` ```subtractCollection(java.util.Queue<IRectangularArea> fromWhatToSubtract, IRectangularArea... whatToSubtract)```
Equivalent to `subtractCollection`(fromWhatToSubtract, java.util.Arrays.asList(whatToSubtract)).
`RectangularArea` `toRectangularArea()`
Equivalent to `RectangularArea.valueOf`(thisInstance).
`java.lang.String` `toString()`
Returns a brief string description of this object.
`static IRectangularArea` ```valueOf(IPoint min, IPoint max)```
Returns an instance of this class with the given minimal vertex min and maximal vertex max.
`static IRectangularArea` `valueOf(IRange... coordRanges)`
Returns the Cartesian product of the specified coordinate ranges.
`static IRectangularArea` `valueOf(RectangularArea area)`
Returns a new rectangular area with the same coordinates as the given area.
`IPoint` `width()`
Returns all sizes of this rectangular area, decreased by 1, in a form of `IPoint`.
`long` `width(int coordIndex)`
Returns `max`(coordIndex) - `min`(coordIndex).
`long[]` `widths()`
Returns the sizes of this rectangular area along all dimensions, decreased by 1.
• ### Methods inherited from class java.lang.Object

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

• #### valueOf

```public static IRectangularArea valueOf(IPoint min,
IPoint 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 max.`coord`(i)-min.`coord`(i)+1 > Long.MAX_VALUE (more precisely, if this Java expression is nonpositive due to integer overflow), or if min.`coord`(i) <= -Long.MAX_VALUE, or if max.`coord`(i) == Long.MAX_VALUE.
• #### valueOf

`public static IRectangularArea valueOf(IRange... 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).
• #### min

`public IPoint 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 IPoint 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 long[] 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.
• #### widths

`public long[] widths()`
Returns the sizes of this rectangular area along all dimensions, decreased by 1. The returned array consists of `coordCount()` elements, and the element #k contains `width`(k).
Returns:
the sizes of this rectangular area along all dimensions, decreased by 1.
• #### ranges

`public IRange[] 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(IRectangularArea 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 IRectangularArea intersection(IRectangularArea 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) ? `IRectangularArea.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<IRectangularArea> difference(java.util.Collection<IRectangularArea> results,
IRectangularArea 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.
`subtractCollection(java.util.Queue, java.util.Collection)`
• #### subtractCollection

```public static java.util.Queue<IRectangularArea> subtractCollection(java.util.Queue<IRectangularArea> fromWhatToSubtract,
java.util.Collection<IRectangularArea> 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 (IRectangularArea area : whatToSubtract) {
for (int i = 0, n = fromWhatToSubtract.size(); i < n; i++) {
IRectangularArea 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()`.
`subtractCollection(java.util.Queue, IRectangularArea...)`
• #### subtractCollection

```public static java.util.Queue<IRectangularArea> subtractCollection(java.util.Queue<IRectangularArea> fromWhatToSubtract,
IRectangularArea... 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 IRectangularArea expand(IRectangularArea area)`
Returns the minimal rectangular area, containing this and the passed area. Equivalent to
````IRectangularArea.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 long parallelDistance(IPoint 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 long parallelDistance(long... coordinates)`
Equivalent to `parallelDistance`(`IPoint.valueOf`(coordinates)), but works faster because does not require to create an instance of `IPoint` 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 long parallelDistance(long x,
long y)```
Equivalent to `parallelDistance`(`IPoint.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 long parallelDistance(long x,
long y,
long z)```
Equivalent to `parallelDistance`(`IPoint.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 IRectangularArea shift(IPoint 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)). Note that integer overflow is not checked here!
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, or if the result is illegal due to the integer overflow.
• #### toRectangularArea

`public RectangularArea toRectangularArea()`
Equivalent to `RectangularArea.valueOf`(thisInstance).
Returns:
the rectangular area with same real coordinates as this one.
• #### 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 IRectangularArea, ((IRectangularArea)obj).min().equals(this.min()) and ((IRectangularArea)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.