Class IPoint

java.lang.Object
net.algart.math.IPoint
All Implemented Interfaces:
Comparable<IPoint>

public class IPoint extends Object implements Comparable<IPoint>

Point in multidimensional space with integer coordinates. Represented as an array of long numbers.

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

Author:
Daniel Alievsky
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    add(IPoint point)
    Returns the vector sum of this and given point: every coordinate #i in the result is thisInstance.coord(i)+point.coord(i).
    Equivalent of add(IPoint) with the only difference: in a case of long overflow (when the result cannot be exactly represented by 64-bit long integers), this method throws ArithmeticException.
    addToAllCoordinates(long increment)
    Adds the given value to all coordinates of this point and returns the resulting point: every coordinate #i in the result is thisInstance.coord(i)+increment.
    int
    Compares points lexicographically.
    int
    compareTo(IPoint o, int firstCoordIndex)
    Compares points lexicographically alike compareTo(IPoint) method, but with the cyclical shift of all indexes of coordinates: the coordinate #firstCoordIndex instead of x, #firstCoordIndex+1 instead of y, etc.
    long
    coord(int coordIndex)
    Returns the coordinate #coordIndex: x-coordinate for coordIndex=0, y-coordinate for coordIndex=1, etc.
    int
    Returns the number of dimensions of this point.
    long[]
    Returns all coordinates of this point.
    long[]
    coordinates(long[] result)
    Copies all coordinates of this point into result array.
    double
    Returns the minimal distance between this point and any point from the passed collection.
    double
    Returns the distance between this point and the origin of coordinates.
    boolean
    Indicates whether some other point is equal to this instance, that is the number of coordinates is the same and all corresponding coordinates are equal.
    int
    Returns the hash code of this point.
    boolean
    Returns true if this point is the origin of coordinates.
    max(IPoint point)
    Returns the coordinate-wise maximum of this and given point: every coordinate #i in the result is Math.max(thisInstance.coord(i),point.coord(i)).
    static IPoint
    maxValue(int coordCount)
    Returns the "maximal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Long.MAX_VALUE.
    min(IPoint point)
    Returns the coordinate-wise minimum of this and given point: every coordinate #i in the result is Math.min(thisInstance.coord(i),point.coord(i)).
    static IPoint
    minValue(int coordCount)
    Returns the "minimal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Long.MIN_VALUE.
    multiply(double multiplier)
    Returns the product of this point and the given scalar multiplier: every coordinate #i in the result is (long)(thisInstance.coord(i)*multiplier).
    static IPoint
    origin(int coordCount)
    Returns the origin of coordinates in n-dimensional space, where n=coordCount is the argument of this method.
    projectionAlongAxis(int coordIndex)
    Returns the projection of this point along the given axis with the number of coordinates, decreased by 1.
    roundedMultiply(double multiplier)
    Returns the product of this point and the given scalar multiplier: every coordinate #i in the result is StrictMath.round(thisInstance.coord(i)*multiplier).
    roundedScale(double... multipliers)
    Returns new point, each coordinate #i of which is StrictMath.round(thisInstance.coord(i)*multipliers[i]).
    static IPoint
    roundOf(Point point)
    Returns a new point with the same coordinates as the given real point.
    double
    Returns the scalar product of this and given point.
    scale(double... multipliers)
    Returns new point, each coordinate #i of which is (long)(thisInstance.coord(i)*multipliers[i]).
    void
    scaleAndShift(double[] resultCoordinates, double[] multipliers, Point shift)
    More efficient version of scaleAndShift(double[], Point) method, which stores the coordinates of the result in the passed Java array instead of creating new instance of this class.
    scaleAndShift(double[] multipliers, Point shift)
    Returns new point, each coordinate #i of which is shift.coord(i)+thisInstance.coord(i)*multipliers[i].
    shiftAlongAxis(int coordIndex, long shift)
    Returns this point shifted by the passed shift along the axis #coordIndex.
    Returns the vector difference of this and given point: every coordinate #i in the result is thisInstance.coord(i)-point.coord(i).
    Equivalent of subtract(IPoint) with the only difference: in a case of long overflow (when the result cannot be exactly represented by 64-bit long integers), this method throws ArithmeticException.
    Returns the symmetric point relatively the origin of coordinates.
    long
    toOneDimensional(long[] dimensions, boolean pseudoCyclicTruncation)
    Returns the index in the one-dimensional array, storing (in usual order) some n-dimensional matrix with given dimensions, corresponding to the position in this matrix, describing by coordinates of this point.
    Equivalent to Point.valueOf(thisInstance).
    Returns a brief string description of this object.
    static IPoint
    valueOf(long x)
    Returns a new 1-dimensional point with the given coordinate.
    static IPoint
    valueOf(long... coordinates)
    Returns a new point with the given set of coordinates: x, y, z, ...
    static IPoint
    valueOf(long x, long y)
    Returns a new 2-dimensional point with the given coordinates.
    static IPoint
    valueOf(long x, long y, long z)
    Returns a new 3-dimensional point with the given coordinates.
    static IPoint
    valueOf(Point point)
    Returns a new point with the same coordinates as the given real point.
    static IPoint
    valueOfEqualCoordinates(int coordCount, long filler)
    Returns a new point in n-dimensional space, where n=coordCount and all coordinates of the point are equal to the given value filler.
    long
    x()
    Returns the x-coordinate: equivalent to coord(0).
    long
    y()
    Returns y-coordinate: equivalent to coord(1).
    long
    z()
    Returns z-coordinate: equivalent to coord(2).

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Method Details

    • valueOf

      public static IPoint valueOf(long... coordinates)
      Returns a new point with the given set of coordinates: x, y, z, ... For example, valueOf(x,y) returns the 2D point with given coordinates.

      The coordinates array must contain at least 1 element.

      The passed coordinates array is cloned by this method: no references to it are maintained by the created object.

      Parameters:
      coordinates - cartesian coordinates of the point.
      Returns:
      the point with the given coordinates.
      Throws:
      NullPointerException - if the passed array is null.
      IllegalArgumentException - if the passed array is empty (no coordinates are passed).
    • valueOf

      public static IPoint valueOf(long x)
      Returns a new 1-dimensional point with the given coordinate.
      Parameters:
      x - cartesian coordinate of the point.
      Returns:
      point with the given coordinates.
    • valueOf

      public static IPoint valueOf(long x, long y)
      Returns a new 2-dimensional point with the given coordinates.
      Parameters:
      x - cartesian x-coordinate of the point.
      y - cartesian y-coordinate of the point.
      Returns:
      point with the given coordinates.
    • valueOf

      public static IPoint valueOf(long x, long y, long z)
      Returns a new 3-dimensional point with the given coordinates.
      Parameters:
      x - cartesian x-coordinate of the point.
      y - cartesian y-coordinate of the point.
      z - cartesian z-coordinate of the point.
      Returns:
      point with the given coordinates.
    • valueOfEqualCoordinates

      public static IPoint valueOfEqualCoordinates(int coordCount, long filler)
      Returns a new point in n-dimensional space, where n=coordCount and all coordinates of the point are equal to the given value filler. For example, valueOfEqualCoordinates(3, 1) returns the 3D point (1,1,1). If filler==0, this method is equivalent to origin(coordCount).
      Parameters:
      coordCount - the number of dimensions.
      filler - the value of each coordinate of the created point.
      Returns:
      the point with equal coordinates.
      Throws:
      IllegalArgumentException - if the passed number of dimensions is zero or negative.
    • origin

      public static IPoint origin(int coordCount)
      Returns the origin of coordinates in n-dimensional space, where n=coordCount is the argument of this method.
      Parameters:
      coordCount - the number of dimensions.
      Returns:
      the origin of coordinates in n-dimensional space.
      Throws:
      IllegalArgumentException - if the passed number of dimensions is zero or negative.
    • minValue

      public static IPoint minValue(int coordCount)
      Returns the "minimal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Long.MIN_VALUE.
      Parameters:
      coordCount - the number of dimensions.
      Returns:
      the "minimal" point in n-dimensional space.
      Throws:
      IllegalArgumentException - if the passed number of dimensions is zero or negative.
    • maxValue

      public static IPoint maxValue(int coordCount)
      Returns the "maximal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Long.MAX_VALUE.
      Parameters:
      coordCount - the number of dimensions.
      Returns:
      the "maximal" point in n-dimensional space.
      Throws:
      IllegalArgumentException - if the passed number of dimensions is zero or negative.
    • valueOf

      public static IPoint valueOf(Point point)
      Returns a new point with the same coordinates as the given real point. All double coordinates of the passed real point are converted to long coordinates of the returned point by standard Java typecast (long)doubleValue.
      Parameters:
      point - the real point.
      Returns:
      the integer point with same (cast) coordinates.
      Throws:
      NullPointerException - if the passed point is null.
    • roundOf

      public static IPoint roundOf(Point point)
      Returns a new point with the same coordinates as the given real point. All double coordinates of the passed real point are converted to long coordinates of the returned point by StrictMath.round method.
      Parameters:
      point - the real point.
      Returns:
      the integer point with same (rounded) coordinates.
      Throws:
      NullPointerException - if the passed point is null.
    • coordCount

      public int coordCount()
      Returns the number of dimensions of this point. Equivalent to coordinates().length, but works faster.

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

      Returns:
      the number of dimensions of this point.
    • coordinates

      public long[] coordinates()
      Returns all coordinates of this point. The element #0 of the returned array is x-coordinate, the element #1 is y-coordinate, etc. The length of the returned array is the number of dimensions of this point.

      The returned array is a clone of the internal coordinates array stored in this object. The returned array is never empty (its length >0 always).

      Returns:
      all coordinates of this point.
    • coordinates

      public long[] coordinates(long[] result)
      Copies all coordinates of this point into result array. The element #0 of this array will contain x-coordinate, the element #1 will contain y-coordinate, etc. The length of the passed array must be not less than the number of dimensions of this point.
      Parameters:
      result - the array where you want to store results.
      Returns:
      a reference to the passed result array.
      Throws:
      NullPointerException - if result argument is null.
      IllegalArgumentException - if result.length<coordCount().
    • coord

      public long coord(int coordIndex)
      Returns the coordinate #coordIndex: x-coordinate for coordIndex=0, y-coordinate for coordIndex=1, etc.
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      the coordinate.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().
    • x

      public long x()
      Returns the x-coordinate: equivalent to coord(0).
      Returns:
      x-coordinate.
    • y

      public long y()
      Returns y-coordinate: equivalent to coord(1). The only difference: in a case of 1-dimensional point (coordCount()<2), this method throws IllegalStateException instead of IndexOutOfBoundsException.
      Returns:
      y-coordinate.
      Throws:
      IllegalStateException - if coordCount()<2.
    • z

      public long z()
      Returns z-coordinate: equivalent to coord(2). The only difference: in a case of 1- or 2-dimensional point (coordCount()<3), this method throws IllegalStateException instead of IndexOutOfBoundsException.
      Returns:
      z-coordinate.
      Throws:
      IllegalStateException - if coordCount()<3.
    • isOrigin

      public boolean isOrigin()
      Returns true if this point is the origin of coordinates. In other words, returns true if all coordinates of this point are zero.
      Returns:
      true if this point is the origin of coordinates.
    • distanceFromOrigin

      public double distanceFromOrigin()
      Returns the distance between this point and the origin of coordinates.
      Returns:
      the distance between this point and the origin of coordinates.
    • distanceFrom

      public double distanceFrom(Collection<IPoint> points)
      Returns the minimal distance between this point and any point from the passed collection. If is also called the Hausdorff distance between the point and the point set. If the passed collection is empty, returns Double.POSITIVE_INFINITY.
      Parameters:
      points - some collection of points.
      Returns:
      the Hausdorff distance from this point to the set of points, passed via the collection.
      Throws:
      NullPointerException - if the argument is null or if some elements of the passed collection are null.
      IllegalArgumentException - if the numbers of dimensions in this point and in some of the given points are different.
    • add

      public IPoint add(IPoint point)
      Returns the vector sum of this and given point: every coordinate #i in the result is thisInstance.coord(i)+point.coord(i).
      Parameters:
      point - the added point.
      Returns:
      the vector sum of this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
    • subtract

      public IPoint subtract(IPoint point)
      Returns the vector difference of this and given point: every coordinate #i in the result is thisInstance.coord(i)-point.coord(i).
      Parameters:
      point - the subtracted point.
      Returns:
      the vector difference of this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
    • min

      public IPoint min(IPoint point)
      Returns the coordinate-wise minimum of this and given point: every coordinate #i in the result is Math.min(thisInstance.coord(i),point.coord(i)).
      Parameters:
      point - the compared point.
      Returns:
      the coordinate-wise minimum this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
    • max

      public IPoint max(IPoint point)
      Returns the coordinate-wise maximum of this and given point: every coordinate #i in the result is Math.max(thisInstance.coord(i),point.coord(i)).
      Parameters:
      point - the compared point.
      Returns:
      the coordinate-wise maximum this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
    • addToAllCoordinates

      public IPoint addToAllCoordinates(long increment)
      Adds the given value to all coordinates of this point and returns the resulting point: every coordinate #i in the result is thisInstance.coord(i)+increment. In other words, shifts this point along all axes by the given value.

      Equivalent to add(IPoint.valueOfEqualCoordinates(n,increment)), where n=coordCount().

      Parameters:
      increment - the value, which will be added to all coordinates of this point.
      Returns:
      this resulting point.
    • roundedMultiply

      public IPoint roundedMultiply(double multiplier)
      Returns the product of this point and the given scalar multiplier: every coordinate #i in the result is StrictMath.round(thisInstance.coord(i)*multiplier).

      Equivalent to roundedScale(double...multipliers), where all coordCount() arguments of that method are equal to multiplier.

      Parameters:
      multiplier - the multiplier.
      Returns:
      the product of this point and the given scalar multiplier.
    • roundedScale

      public IPoint roundedScale(double... multipliers)
      Returns new point, each coordinate #i of which is StrictMath.round(thisInstance.coord(i)*multipliers[i]). The length of multipliers array must be equal to coordCount().

      Note: this method does not perform actual multiplication to multipliers, equal to 1.0, 0.0 and −1.0. If the condition multipliers[k]==1.0 is true for some k, then the coordinate #k is just copied from this point into the result. If the condition multipliers[k]==0.0 is true for some k, then the coordinate #k in the result will be 0.0 (always +0.0, regardless of the sign of this coordinate in the source point). If the condition multipliers[k]==-1.0 is true for some k, then the coordinate #k in the result will be equal to -coord(k).

      Parameters:
      multipliers - the multipliers for all coordinates.
      Returns:
      the point, each coordinate #i of which is product of the corresponding coordinate #i of this one and the corresponding multiplier multiplier[i].
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions is not equal to multipliers.length.
    • scaleAndShift

      public Point scaleAndShift(double[] multipliers, Point shift)
      Returns new point, each coordinate #i of which is shift.coord(i)+thisInstance.coord(i)*multipliers[i]. The length of multipliers array must be equal to coordCount().

      Note: this method does not perform actual multiplication to multipliers, equal to 1.0, 0.0 and −1.0. If the condition multipliers[k]==1.0 is true for some k, then the coordinate #k will be equal to shift.coord(k)+thisInstance.coord(k). If the condition multipliers[k]==0.0 is true for some k, then the coordinate #k in the result will be equal to shift.coord(k). If the condition multipliers[k]==-1.0 is true for some k, then the coordinate #k in the result will be equal to shift.coord(k)-thisInstance.coord(k).

      Parameters:
      multipliers - the multipliers for all coordinates.
      shift - the shift along all coordinates.
      Returns:
      the point, each coordinate #i of which is product of the corresponding coordinate #i of this one and the corresponding multiplier multiplier[i], incremented by the corresponding coordinate shift.coord(i).
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the numbers of dimensions is not equal to multipliers.length.
    • scaleAndShift

      public void scaleAndShift(double[] resultCoordinates, double[] multipliers, Point shift)
      More efficient version of scaleAndShift(double[], Point) method, which stores the coordinates of the result in the passed Java array instead of creating new instance of this class. Equivalent to the following call: scaleAndShift(multipliers,shift).coordinates(resultCoordinates), but works little faster.
      Parameters:
      resultCoordinates - Java array for storing results.
      multipliers - the multipliers for all coordinates.
      shift - the shift along all coordinates.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the numbers of dimensions is greater than resultCoordinates.length or is not equal to multipliers.length.
    • shiftAlongAxis

      public IPoint shiftAlongAxis(int coordIndex, long shift)
      Returns this point shifted by the passed shift along the axis #coordIndex. Equivalent to add(p), where p is the point with coordinates p0, p1, ..., pk=0 for k!=coordIndex, pk=shift for k=coordIndex.
      Parameters:
      coordIndex - the index of the axis.
      shift - the shift along this axis.
      Returns:
      this point shifted along this axis.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().
    • scalarProduct

      public double scalarProduct(IPoint point)
      Returns the scalar product of this and given point. The result is the sum of all products (double)thisInstance.coord(i)*(double)point.coord(i) for all coordinate indexes i.
      Parameters:
      point - another point.
      Returns:
      the scalar product of this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
    • symmetric

      public IPoint symmetric()
      Returns the symmetric point relatively the origin of coordinates. Equivalent to multiply(-1.0).
      Returns:
      the symmetric point relatively the origin of coordinates.
    • projectionAlongAxis

      public IPoint projectionAlongAxis(int coordIndex)
      Returns the projection of this point along the given axis with the number of coordinates, decreased by 1. Namely, the resulting point P has coordCount()−1 coordinates, equal to P.coord(i)=thisInstance.coord(i'), i'=i for i<coordIndex or i'=i+1 for icoordIndex.
      Parameters:
      coordIndex - the number of coordinate, along which the projecting is performed.
      Returns:
      the projection of this point along the coordinates axis #coordIndex.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().
      IllegalStateException - if this point is 1-dimensional (coordCount()==1).
    • compareTo

      public int compareTo(IPoint o)
      Compares points lexicographically.

      More precisely, let xi is thisInstance.coord(i) for 0<=i<thisInstance.coordCount() and xi=0 for i>=thisInstance.coordCount(). Then, let yi is o.coord(i) for 0<=i<o.coordCount() and yi=0 for i>=o.coordCount(). This method returns a negative integer if there is such index k that xk<yk and xi=yi for all i>k; this method returns a positive integer if there is such index k that xk>yk and xi=yi for all i>k. If all xi=yi, this method returns a negative integer, 0 or a positive integer if thisInstance.coordCount() is less than, equal to, or greater than o.coordCount().

      Specified by:
      compareTo in interface Comparable<IPoint>
      Parameters:
      o - the point to be compared.
      Returns:
      negative integer, zero, or a positive integer as this point is lexicographically less than, equal to, or greater than o.
      Throws:
      NullPointerException - if the argument is null.
    • compareTo

      public int compareTo(IPoint o, int firstCoordIndex)
      Compares points lexicographically alike compareTo(IPoint) method, but with the cyclical shift of all indexes of coordinates: the coordinate #firstCoordIndex instead of x, #firstCoordIndex+1 instead of y, etc.

      More precisely, let n=max(thisInstance.coordCount(),o.coordCount()), xi is thisInstance.coord((i+firstCoordIndex)%n), yi is o.coord((i+firstCoordIndex)%n). As in compareTo(IPoint) method, we suppose here that all coordinates coord(k) with k>=coordCount() are zero. This method returns a negative integer if there is such index k that xk<yk and xi=yi for all i>k; this method returns a positive integer if there is such index k that xk>yk and xi=yi for all i>k. If all xi=yi, this method returns a negative integer, 0 or a positive integer if thisInstance.coordCount() is less than, equal to, or greater than o.coordCount().

      Parameters:
      o - the point to be compared.
      firstCoordIndex - the index of "first" coordinate, that is compared after all other coordinates.
      Returns:
      negative integer, zero, or a positive integer as this point is lexicographically less than, equal to, or greater than o.
      Throws:
      NullPointerException - if the o argument is null.
      IllegalArgumentException - if firstCoordIndex is negative.
    • toString

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

      The result of this method may depend on implementation and usually contains a list of all point coordinates.

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

      public int hashCode()
      Returns the hash code of this point. The result depends on all coordinates.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this point.
    • equals

      public boolean equals(Object obj)
      Indicates whether some other point is equal to this instance, that is the number of coordinates is the same and all corresponding coordinates are equal.
      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 point equal to this one.
    • addExact

      public IPoint addExact(IPoint point)
      Equivalent of add(IPoint) with the only difference: in a case of long overflow (when the result cannot be exactly represented by 64-bit long integers), this method throws ArithmeticException.
      Parameters:
      point - the added point.
      Returns:
      the vector sum of this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
      ArithmeticException - in a case of long overflow.
    • subtractExact

      public IPoint subtractExact(IPoint point)
      Equivalent of subtract(IPoint) with the only difference: in a case of long overflow (when the result cannot be exactly represented by 64-bit long integers), this method throws ArithmeticException.
      Parameters:
      point - the subtracted point.
      Returns:
      the vector difference of this and given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions in this and given points are different.
      ArithmeticException - in a case of long overflow.
    • multiply

      public IPoint multiply(double multiplier)
      Returns the product of this point and the given scalar multiplier: every coordinate #i in the result is (long)(thisInstance.coord(i)*multiplier).

      Equivalent to scale(double...multipliers), where all coordCount() arguments of that method are equal to multiplier.

      Parameters:
      multiplier - the multiplier.
      Returns:
      the product of this point and the given scalar multiplier.
    • scale

      public IPoint scale(double... multipliers)
      Returns new point, each coordinate #i of which is (long)(thisInstance.coord(i)*multipliers[i]). The length of multipliers array must be equal to coordCount().

      Note: this method does not perform actual multiplication to multipliers, equal to 1.0, 0.0 and −1.0. If the condition multipliers[k]==1.0 is true for some k, then the coordinate #k is just copied from this point into the result. If the condition multipliers[k]==0.0 is true for some k, then the coordinate #k in the result will be 0.0 (always +0.0, regardless of the sign of this coordinate in the source point). If the condition multipliers[k]==-1.0 is true for some k, then the coordinate #k in the result will be equal to -coord(k).

      Parameters:
      multipliers - the multipliers for all coordinates.
      Returns:
      the point, each coordinate #i of which is product of the corresponding coordinate #i of this one and the corresponding multiplier multiplier[i].
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of dimensions is not equal to multipliers.length.
    • toOneDimensional

      public long toOneDimensional(long[] dimensions, boolean pseudoCyclicTruncation)
      Returns the index in the one-dimensional array, storing (in usual order) some n-dimensional matrix with given dimensions, corresponding to the position in this matrix, describing by coordinates of this point.

      More precisely, if the pseudoCyclicTruncation argument is false, returns the following value: shift = coord(0) + coord(1)*dim0 + coord(2)*dim0*dim1 + ... + coord(n-1)*dim0*dim1*...*dimn-2 (n = coordCount(), where dimi=i>=dimensions.length?1:dimensions[i]. If pseudoCyclicTruncation is true, returns the positive remainder of division of this value by the product of all dimensions:

       shift%product >= 0 ? shift%product : shift%product + product,
       
      product = dim0*dim1*...*dimn-1. (In the special case product==0, if pseudoCyclicTruncation is true, this method returns 0 and does not throw "division by zero" exception.)

      All elements of dimensions array must be positive or zero. All point coordinates are always used, regardless of the length of dimensions array.

      If pseudoCyclicTruncation is true and the product of all dimensions product = dim0*dim1*...*dimn-1 is not greater than Long.MAX_VALUE, then all calculations are performed absolutely precisely, even in a case when the direct calculation according the formulas above leads to overflow (because some of values in these formulas are out of Long.MIN_VALUE..Long.MAX_VALUE range). However, if product>Long.MAX_VALUE, the results will be probably incorrect due to overflow.

      If pseudoCyclicTruncation is false, the result is calculated by the traditional Horner scheme without any overflow checks, using standard Java long arithmetic:

       (...(coord(n-1)*dimn-2+coord(n-2))*dimn-3+...)*dim0+coord(0)
       
      So, the result can be incorrect in a case of overflow.
      Parameters:
      dimensions - the dimensions of some n-dimensional matrix, stored in the one-dimensional array.
      pseudoCyclicTruncation - if true, the result is replaced with the positive remainder of division by the product of all dimensions.
      Returns:
      the index in this array, corresponding the position in the matrix, describing by this point.
      Throws:
      NullPointerException - if dimensions argument is null.
      IllegalArgumentException - if some elements of dimensions array are negative (however note, that this method does not check elements, indexes of which are >=coordCount())
    • toPoint

      public Point toPoint()
      Equivalent to Point.valueOf(thisInstance).
      Returns:
      the real point with same coordinates.