Package net.algart.math

Class IRectangularArea

java.lang.Object
net.algart.math.IRectangularArea
public class IRectangularArea extends Object

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

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

min.coord(0) ≤ x0 ≤ max.coord(0),
min.coord(1) ≤ x1 ≤ max.coord(1),
...,
min.coord(n-1) ≤ xn−1 ≤ max.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), the coordinates of the minimal and maximal vertices are always in range -Long.MAX_VALUE+1..Long.MAX_VALUE-1, and their difference is always less than Long.MAX_VALUE. In other words, "max.coord(i)-min.coord(i)+1" expression, returned by size(int) method, and also "min.coord(i)-1", "min.coord(i)-2" and "max.coord(i)+1" expressions are always calculated without overflow, and the range(int) method is always possible to return an allowed range.

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

Author:
Daniel Alievsky
See Also:

  • Method Details

    • 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:
      NullPointerException - if one of arguments is null.
      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:
      NullPointerException - if the argument is null or if one of specified coordRanges is null.
      IllegalArgumentException - if the passed array is empty (no ranges are passed).

    • valueOf

      public static IRectangularArea valueOf(long minX, long maxX)
      Returns a 1-dimensional rectangular area (range) with the given minimal and maximal vertex. Equivalent to 
       valueOf(
      IPoint.valueOf(minX),
      IPoint.valueOf(maxX));
      Parameters:
      minX - the minimal x-coordinate, inclusive.
      maxX - the maximal x-coordinate, inclusive.
      Returns:
      the new 1-dimensional rectangular area.
      Throws:
      IllegalArgumentException - in the same situations as valueOf(IPoint, IPoint) method.

    • valueOf

      public static IRectangularArea valueOf(long minX, long minY, long maxX, long maxY)
      Returns a 2-dimensional rectangle with the given minimal and maximal vertex. Equivalent to 
       valueOf(
      IPoint.valueOf(minX, minY),
      IPoint.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:
      IllegalArgumentException - in the same situations as valueOf(IPoint, IPoint) method.

    • valueOf

      public static IRectangularArea valueOf(long minX, long minY, long minZ, long maxX, long maxY, long maxZ)
      Returns a 3-dimensional parallelepiped with the given minimal and maximal vertex. Equivalent to 
       valueOf(
      IPoint.valueOf(minX, minY, minZ),
      IPoint.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:
      IllegalArgumentException - in the same situations as valueOf(IPoint, IPoint) method.

    • valueOf

      public static IRectangularArea valueOf(RectangularArea area)
      Returns a new rectangular area with the same coordinates as the given area. All double coordinates of the passed area are converted to long coordinates of the returned area by standard Java typecast (long)doubleValue. Equivalent to valueOf(IPoint.valueOf(area.min()), IPoint.valueOf(area.max())).
      Parameters:
      area - the real rectangular area.
      Returns:
      the integer rectangular area with same (cast) coordinates.
      Throws:
      NullPointerException - if the passed area is null.
      IllegalArgumentException - if the points IPoint.valueOf(area.min()) and IPoint.valueOf(area.max()) do not match requirements of valueOf(IPoint, IPoint) method.

    • roundOf

      public static IRectangularArea roundOf(RectangularArea area)
      Returns a new rectangular area with the same coordinates as the given area. All double coordinates of the passed area are converted to long coordinates of the returned area by StrictMath.round method. Java typecast (long)doubleValue. Equivalent to valueOf(IPoint.roundOf(area.min()), IPoint.roundOf(area.max())).
      Parameters:
      area - the real rectangular area.
      Returns:
      the integer rectangular area with same (rounded) coordinates.
      Throws:
      NullPointerException - if the passed area is null.
      IllegalArgumentException - if the points IPoint.valueOf(area.min()) and IPoint.valueOf(area.max()) do not match requirements of valueOf(IPoint, IPoint) method.

    • coordCount

      public int coordCount()
      Returns the number of dimensions of this rectangular area. Equivalent to min().coordCount() or max().coordCount(), but works faster.

      The result of this method is always positive (>0).

      Returns:
      the number of dimensions of this rectangular area.

    • 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.

    • size

      public IPoint size()
      Returns all sizes of this rectangular area in a form of IPoint. Equivalent to IPoint.valueOf(sizes()). The coordinates of the returned point are greater by 1 than coordinates of max().subtract(min()).
      Returns:
      all sizes of this rectangular area in a form of IPoint.

    • width

      public IPoint width()
      Returns all sizes of this rectangular area, decreased by 1, in a form of IPoint. Equivalent to IPoint.valueOf(widths()). The coordinates of the returned point are equal to coordinates of max().subtract(min()).
      Returns:
      all sizes of this rectangular area, decreased by 1, in a form of IPoint.

    • min

      public long min(int coordIndex)
      Returns min().coord(coordIndex).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      min().coord(coordIndex).
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • max

      public long max(int coordIndex)
      Returns max().coord(coordIndex).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      max().coord(coordIndex).
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • size

      public long size(int coordIndex)
      Returns max(coordIndex) - min(coordIndex) + 1.
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      max(coordIndex) - min(coordIndex) + 1.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • width

      public long width(int coordIndex)
      Returns max(coordIndex) - min(coordIndex).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      max(coordIndex) - min(coordIndex).
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • minX

      public long minX()
      Returns min().x().
      Returns:
      min().x().

    • maxX

      public long maxX()
      Returns max().x().
      Returns:
      max().x().

    • sizeX

      public long sizeX()
      Returns maxX() - minX() + 1.
      Returns:
      maxX() - minX() + 1.

    • widthX

      public long widthX()
      Returns maxX() - minX().
      Returns:
      maxX() - minX().

    • minY

      public long minY()
      Returns min().y().
      Returns:
      min().y().
      Throws:
      IllegalStateException - if coordCount()<2.

    • maxY

      public long maxY()
      Returns max().y().
      Returns:
      max().y().
      Throws:
      IllegalStateException - if coordCount()<2.

    • sizeY

      public long sizeY()
      Returns maxY() - minY() + 1.
      Returns:
      maxY() - minY() + 1.
      Throws:
      IllegalStateException - if coordCount()<2.

    • widthY

      public long widthY()
      Returns maxY() - minY().
      Returns:
      maxY() - minY().
      Throws:
      IllegalStateException - if coordCount()<2.

    • minZ

      public long minZ()
      Returns min().z().
      Returns:
      min().z().
      Throws:
      IllegalStateException - if coordCount()<3.

    • maxZ

      public long maxZ()
      Returns max().z().
      Returns:
      max().z().
      Throws:
      IllegalStateException - if coordCount()<3.

    • sizeZ

      public long sizeZ()
      Returns maxZ() - minZ() + 1.
      Returns:
      maxZ() - minZ() + 1.
      Throws:
      IllegalStateException - if coordCount()<3.

    • widthZ

      public long widthZ()
      Returns maxZ() - minZ().
      Returns:
      maxZ() - minZ().
      Throws:
      IllegalStateException - if coordCount()<3.

    • 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.

    • volume

      public double volume()
      Returns the volume of this rectangular area: the product of all sizes returned by sizes() method. This area is calculated in double values.
      Returns:
      the multidimensional volume of this rectangular area (usual area in 2-dimensional case).

    • range

      public IRange range(int coordIndex)
      Returns IRange.valueOf(min(coordIndex), max(coordIndex)).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      IRange.valueOf(min(coordIndex), max(coordIndex)).

    • 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.

    • contains

      public boolean contains(IPoint point)
      Returns true if and only if min(k)<=point.coord(k)<=max(k) for all k.
      Parameters:
      point - the checked point.
      Returns:
      true if this rectangular area contains the given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of this instance.

    • contains

      public static boolean contains(Collection<IRectangularArea> areas, IPoint point)
      Returns true if at least one of the specified areas contains the passed point (see contains(IPoint) method).
      Parameters:
      areas - list of checked rectangular areas.
      point - the checked point.
      Returns:
      true if one of the passed areas contains the given point.
      Throws:
      NullPointerException - if one of the arguments or one of the areas is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of one of areas.

    • contains

      public boolean contains(IRectangularArea area)
      Returns true if and only if min(k)<=area.min(k) and area.max(k)<=max(k) for all k.
      Parameters:
      area - the checked rectangular area.
      Returns:
      true if the checked rectangular area is a subset of this area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • contains

      public static boolean contains(Collection<IRectangularArea> areas, IRectangularArea area)
      Returns true if at least one of the specified areas contains the passed area (see contains(IRectangularArea) method).
      Parameters:
      areas - list of checked rectangular areas.
      area - the checked area.
      Returns:
      true if one of the passed areas (1st argument) contains the given area (2nd argument).
      Throws:
      NullPointerException - if one of the arguments or one of the areas is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of one of areas in the 1st argument.

    • 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:
      NullPointerException - if the argument is null.
      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:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • intersection

      public List<IRectangularArea> intersection(Collection<IRectangularArea> areas)
      Returns a list of set-theoretical intersections A ∩ Bi of this rectangular area (A) and all rectangular areas (Bi), specified by areas argument. If the passed collection doesn't contain areas, intersecting this area, the result will be an empty list.

      Equivalent to the following loop: 

       final List result = ... (some empty list);
 for (IRectangularArea area : areas) {
     IRectangularArea intersection = intersection(area);
     if (intersection != null) {
         result.add(intersection);
     }
 }
      .
      Parameters:
      areas - collection of areas (we find intersection with each from them).
      Returns:
      intersection of this and the second rectangular area or null if they do not intersect.
      Throws:
      NullPointerException - if the argument is null or one of its elements is null.
      IllegalArgumentException - if this rectangular area or some of elements of the passed collection have different coordCount().

    • difference

      public Collection<IRectangularArea> difference(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 (R1∪R2∪...∪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 (new areas will be added to this collection).
      area - the area B, subtracted from this area A.
      Returns:
      a reference to the results argument.
      Throws:
      NullPointerException - if result or area argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.
      See Also:

    • subtractCollection

      public static Queue<IRectangularArea> subtractCollection(Queue<IRectangularArea> fromWhatToSubtract, 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:
      NullPointerException - if fromWhatToSubtract or whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if some of elements of the passed collections have different coordCount().
      See Also:

    • subtractCollection

      public static Queue<IRectangularArea> subtractCollection(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:
      NullPointerException - if fromWhatToSubtract or whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if some of elements of the passed collection and array have different coordCount().

    • subtract

      public Queue<IRectangularArea> subtract(Collection<IRectangularArea> whatToSubtract)
      Equivalent to subtractCollection(fromWhatToSubtract, whatToSubtract, where fromWhatToSubtract contains this object as the only element.
      Parameters:
      whatToSubtract - the subtrahend B.
      Returns:
      new collection, containing the difference A \ B (A = this object, B = union of all whatToSubtract).
      Throws:
      NullPointerException - if whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if this rectangular area or some of elements of the passed collection have different coordCount().

    • subtract

      public Queue<IRectangularArea> subtract(IRectangularArea... whatToSubtract)
      Equivalent to subtract(java.util.Arrays.asList(whatToSubtract)).
      Parameters:
      whatToSubtract - the subtrahend B.
      Returns:
      new collection, containing the difference A \ B (A = this object, B = union of all whatToSubtract).
      Throws:
      NullPointerException - if whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if this rectangular area or some of elements of the passed array have different coordCount().

    • expand

      public IRectangularArea expand(IPoint point)
      Returns the minimal rectangular area, containing this area and the given point. In the returned area, the minimal vertex is equal to thisInstance.min().min(point) and the maximal vertex is equal to thisInstance.max().max(point).
      Parameters:
      point - some point that should be included to the new rectangular area.
      Returns:
      the expanded rectangular area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of this instance, or if the points thisInstance.min().min(point) and thisInstance.max().max(point) do not match requirements of valueOf(IPoint, IPoint) method.

    • 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:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • minimalContainingArea

      public static IRectangularArea minimalContainingArea(Collection<IRectangularArea> areas)
      Returns the minimal rectangular area, containing all passed areas. Equivalent to the loop of expand(IRectangularArea) methods, called for each element of the passed collection, but works faster.

      If the passed collection is empty, returns null.

      Parameters:
      areas - some collection of rectangular areas.
      Returns:
      the minimal rectangular area, containing all them, or null for empty collection.
      Throws:
      NullPointerException - if the argument or one of the passed areas is null.
      IllegalArgumentException - if coordCount() is not equal for all areas.

    • 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(li−pi, pi−ri). 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:
      NullPointerException - if the argument is null.
      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:
      NullPointerException - if coordinates argument is null.
      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:
      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:
      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().addExact(vector), thisInstance.max().addExact(vector))

      Note: the coordinates of new areas are calculated with overflow control.

      Parameters:
      vector - the vector which is added to all vertices of this area.
      Returns:
      the shifted area.
      Throws:
      NullPointerException - if the argument is null.
      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.
      ArithmeticException - in a case of long overflow.

    • shiftBack

      public IRectangularArea shiftBack(IPoint vector)
      Shifts this rectangular area by vector.symmetric() and returns the shifted area. Equivalent to 
      valueOf(thisInstance.min().subtractExact(vector), thisInstance.max().subtractExact(vector))

      Note: the coordinates of new areas are calculated with overflow control.

      Parameters:
      vector - the vector which is subtracted from all vertices of this area.
      Returns:
      the shifted area.
      Throws:
      NullPointerException - if the argument is null.
      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.
      ArithmeticException - in a case of long overflow.

    • dilate

      public IRectangularArea dilate(IPoint expansion)
      Returns this rectangular area, dilated (expanded) according the argument. More precisely, returns 
      IRectangularArea.valueOf(
 thisInstance.min().subtractExact(expansion),
 thisInstance.max().addExact(expansion))
      (but if expansion.isOrigin(), return this object without changes).
      Parameters:
      expansion - how to dilate this area.
      Returns:
      dilated area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if expansion.coordCount() is not equal to the number of dimensions of this instance, or if the result area will be incorrect (see comments to valueOf(IPoint, IPoint) method).
      ArithmeticException - in a case of long overflow.

    • dilate

      public IRectangularArea dilate(long expansion)
      Equivalent to dilate(IPoint.valueOfEqualCoordinates(thisObjects.coordCount(), expansion).
      Parameters:
      expansion - how to dilate this area.
      Returns:
      dilated area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the result area will be incorrect (see comments to valueOf(IPoint, IPoint) method).
      ArithmeticException - in a case of long overflow.

    • dilateStraightOnly

      public List<IRectangularArea> dilateStraightOnly(List<IRectangularArea> results, IPoint expansion)
      Returns this area, dilated according the argument only along coordinate axes, without full hypercube areas near vertices (like in dilate(IPoint) method).

      More precisely, the result is a list, consisting of this area and (usually) 2*coordCount() rectangular areas, lying along facets of this area, like in the following picture: 

           aaaaaaaaaaaa
   bbRRRRRRRRRRRRcc
   bbRRRRRRRRRRRRcc
   bbRRRRRRRRRRRRcc
     ddddddddddd
      This figure shows dilation of some 2-dimensional rectangle R by expansion=IPoint.valueOf(2,1): the results consists of the original rectangle and 4 rectangles a, b (height 1) and c, d (width 2).

      Note: all coordinates of expansion argument must be non-negative (unlike dilate(IPoint) method).

      Note: the coordinates of new areas are calculated with overflow control: if the result cannot be exactly represented by 64-bit long integers, this method throws ArithmeticException.

      If some of coordinates of the point expansion are zero, new areas along the corresponding facets are not added (recanglar area cannot be empty). In particular, if expansion.isOrigin(), the result will contain this area as the only element.

      Parameters:
      results - the list to store results (new areas will be added to the end of this list).
      expansion - how to dilate this area.
      Returns:
      a reference to the results argument.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if expansion.coordCount() is not equal to the number of dimensions of this instance, or if one of coordinates of expansion is negative, or if the result area will be incorrect (see comments to valueOf(IPoint, IPoint) method).
      ArithmeticException - in a case of long overflow.

    • dilateStraightOnly

      public List<IRectangularArea> dilateStraightOnly(List<IRectangularArea> results, long expansion)
      Equivalent to dilateStraightOnly(results, IPoint.valueOfEqualCoordinates(thisObjects.coordCount(), expansion).
      Parameters:
      results - the list to store results (new areas will be added to the end of this list).
      expansion - how to dilate this area.
      Returns:
      a reference to the results argument.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if expansion < 0 or if the result area will be incorrect (see comments to valueOf(IPoint, IPoint) method).
      ArithmeticException - in a case of long overflow.

    • dilate

      public static List<IRectangularArea> dilate(Collection<IRectangularArea> areas, IPoint expansion, boolean straightOnly)
      Dilates all areas, specified by the argument, by dilate or dilateStraightOnly method, and returns the list of dilated areas.

      If straightOnly argument is false, this method is equivalent to the following code: 

       final List result = new ArrayList();
 for (IRectangularArea area : areas) {
     result.add(area.dilate(expansion));
 }

      If straightOnly argument is true, this method is equivalent to the following code: 

       final List result = new ArrayList();
 for (IRectangularArea area : areas) {
     area.dilateStraightOnly(result, expansion);
 }

      Note that in the second case the resulting list will usually contain more elements than the source areas collection.

      Parameters:
      areas - areas to be dilated.
      expansion - how to dilate these areas.
      straightOnly - dilation mode.
      Returns:
      list of dilated areas.
      Throws:
      NullPointerException - if one of the arguments is null or one of areas is null.
      IllegalArgumentException - if expansion.coordCount() is not equal to the number of dimensions of one of areas, or if straightOnly amd one of coordinates of expansion is negative (and collection of areas is not empty), or if one of the result areas will be incorrect (see comments to valueOf(IPoint, IPoint) method).
      ArithmeticException - in a case of long overflow.

    • toRectangularArea

      public RectangularArea toRectangularArea()
      Equivalent to RectangularArea.valueOf(thisInstance).
      Returns:
      the rectangular area with same real coordinates as this one.

    • toString

      public 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 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 Object
      Returns:
      the hash code of this rectangular area.

    • equals

      public boolean equals(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 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.