agi.foundation.coordinates

(agi.foundation.core-2024r3.jar)

Class Rectangular

java.lang.Object

agi.foundation.coordinates.Rectangular

All Implemented Interfaces:

IEquatable<Rectangular>, ImmutableValueType, ValueType, IEquatableEpsilon<Rectangular>

public final class Rectangular
extends Object
implements IEquatable<Rectangular>, IEquatableEpsilon<Rectangular>, ImmutableValueType

A set of rectilinear 2-dimensional coordinates.

The corresponding 3-dimensional coordinates are Cartesian coordinates.

Constructor Summary

Constructors

Constructor and Description
Rectangular() Initializes a new instance.
Rectangular(double[] elements) Initializes a set of Rectangular coordinates from the first 2 consecutive elements in the provided array.
Rectangular(double[] elements, int startIndex) Initializes a set of Rectangular coordinates from 2 consecutive elements in the provided array.
Rectangular(double x, double y) Initializes a set of Rectangular coordinates from the provided values.
Rectangular(Polar coordinates) Initializes a set of Rectangular coordinates from the provided set of Polar coordinates.

Method Summary

Modifier and Type	Method and Description
Rectangular	add(Rectangular other) Adds the specified set of Rectangular coordinates to this instance.
static Rectangular	add(Rectangular left, Rectangular right) Adds a specified set of Rectangular coordinates to another specified set of Cartesian coordinates.
double	cross(Rectangular other) Forms the cross product of the specified set of Rectangular coordinates with this instance.
Rectangular	divide(double scalar) Divides this instance by a scalar.
static Rectangular	divide(Rectangular left, double right) Divides a specified set of Rectangular coordinates by a scalar.
double	dot(Rectangular other) Forms the dot product of the specified set of Rectangular coordinates with this instance.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
static boolean	equals(Rectangular left, Rectangular right) Returns true if the two instances are exactly equal.
boolean	equalsEpsilon(Rectangular other, double epsilon) Indicates whether each coordinate value of another instance of this type is within the required tolerance of the corresponding coordinate value of this instance.
boolean	equalsType(Rectangular other) Indicates whether another instance of this type is exactly equal to this instance.
double	get(int index) Gets the value of the specified element with index of 0 and 1 corresponding to the coordinates X (get), and Y (get).
boolean	getHasZeroMagnitude() Gets a value indicating whether the Magnitude (get) of this instance is zero.
boolean	getIsUndefined() Gets a value indicating whether or not any of the coordinates for this instance have the value Double.NaN.
int	getLength() Gets the number of elements in this set of coordinates.
double	getMagnitude() Gets the magnitude of this instance.
double	getMagnitudeSquared() Gets the square of the Magnitude (get) of this instance.
static Rectangular	getUndefined() Gets a set of Rectangular coordinates with values of Double.NaN.
double	getX() Gets the linear coordinate along the positive x-axis.
double	getY() Gets the linear coordinate along the positive y-axis.
static Rectangular	getZero() Gets a set of Rectangular coordinates with values of zero.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
Rectangular	invert() Inverts this instance.
Rectangular	multiply(double scalar) Multiplies this instance by a scalar.
static Rectangular	multiply(double left, Rectangular right) Multiplies a scalar by a specified set of Rectangular coordinates.
static Rectangular	multiply(Rectangular left, double right) Multiplies a specified set of Rectangular coordinates by a scalar.
static Rectangular	negate(Rectangular coordinates) Negates the specified set of Rectangular coordinates, yielding a new set of Rectangular coordinates.
UnitRectangular	normalize() Forms a set of UnitRectangular coordinates from this instance.
UnitRectangular	normalize(double[] magnitude) Forms a set of UnitRectangular coordinates from this instance and returns the Magnitude (get) of the original instance in the provided parameter.
static boolean	notEquals(Rectangular left, Rectangular right) Returns true if the two instances are not exactly equal.
Rectangular	rotate(double angle) Produces a set of Rectangular coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided angle.
Rectangular	subtract(Rectangular other) Subtracts the specified set of Rectangular coordinates from this instance.
static Rectangular	subtract(Rectangular left, Rectangular right) Subtracts a specified set of Rectangular coordinates from another specified set of Rectangular coordinates.
static Rectangular	toRectangular(UnitRectangular coordinates) Converts a set of UnitRectangular coordinates to a set of Rectangular coordinates.
String	toString() Returns the string representation of the value of this instance.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Rectangular

public Rectangular()

Initializes a new instance.

Rectangular

public Rectangular(double x,
                   double y)

Initializes a set of Rectangular coordinates from the provided values.

Parameters:

x - The linear coordinate along the positive x-axis.

y - The linear coordinate along the positive y-axis.

Rectangular

public Rectangular(@Nonnull
                   Polar coordinates)

Initializes a set of Rectangular coordinates from the provided set of Polar coordinates.

Parameters:

coordinates - The set of Polar coordinates.

Rectangular

public Rectangular(@Nonnull
                   double[] elements)

Initializes a set of Rectangular coordinates from the first 2 consecutive elements in the provided array.

Parameters:

elements - The array of coordinate values.

Throws:

ArgumentNullException - Thrown when elements is null.

ArgumentOutOfRangeException - An object of this type must be constructed from an array with at least 2 elements.

Rectangular

public Rectangular(@Nonnull
                   double[] elements,
                   int startIndex)

Initializes a set of Rectangular coordinates from 2 consecutive elements in the provided array.

Parameters:

elements - The array of coordinate values.

startIndex - The index of the first element in the array to use.

Throws:

ArgumentNullException - Thrown when elements is null.

ArgumentOutOfRangeException - Thrown when an object of this type is constructed from an array with less than 2 elements.

Method Detail

getZero

@Nonnull
public static Rectangular getZero()

Gets a set of Rectangular coordinates with values of zero.

getUndefined

@Nonnull
public static Rectangular getUndefined()

Gets a set of Rectangular coordinates with values of Double.NaN.

Use IsUndefined (get) to test whether a Rectangular instance is undefined since it will return true if any of the coordinate values are Double.NaN.

getX

public final double getX()

Gets the linear coordinate along the positive x-axis.

getY

public final double getY()

Gets the linear coordinate along the positive y-axis.

invert

@Nonnull
public final Rectangular invert()

Inverts this instance.

Returns:

A set of Rectangular coordinates that represents the inverse of this instance.

multiply

@Nonnull
public final Rectangular multiply(double scalar)

Multiplies this instance by a scalar.

Parameters:

scalar - The multiplier, or value which is to multiply this instance.

Returns:

A set of Rectangular coordinates that represents the result of the multiplication.

divide

@Nonnull
public final Rectangular divide(double scalar)

Divides this instance by a scalar.

Parameters:

scalar - The divisor, or value which is to divide this instance.

Returns:

A set of Rectangular coordinates that represents the result of the division.

add

@Nonnull
public final Rectangular add(@Nonnull
                                       Rectangular other)

Adds the specified set of Rectangular coordinates to this instance.

Parameters:

other - The addend, or value which is to be added to this instance.

Returns:

A set of Rectangular coordinates that represents the result of the addition.

subtract

@Nonnull
public final Rectangular subtract(@Nonnull
                                            Rectangular other)

Subtracts the specified set of Rectangular coordinates from this instance.

Parameters:

other - The subtrahend, or value which is to be subtracted from this instance.

Returns:

A set of Rectangular coordinates that represents the result of the subtraction.

dot

public final double dot(@Nonnull
                        Rectangular other)

Forms the dot product of the specified set of Rectangular coordinates with this instance.

Parameters:

other - The set of Rectangular coordinates to dot with this instance.

Returns:

A double that represents the result of the product.

cross

public final double cross(@Nonnull
                          Rectangular other)

Forms the cross product of the specified set of Rectangular coordinates with this instance.

Parameters:

other - The set of Rectangular coordinates to cross with this instance.

Returns:

A double that represents the result of the product.

multiply

@Nonnull
public static Rectangular multiply(@Nonnull
                                             Rectangular left,
                                             double right)

Multiplies a specified set of Rectangular coordinates by a scalar.

Parameters:

left - The multiplicand, or value which is to be multiplied by right.

right - The multiplier, or value which is to multiply left.

Returns:

A set of Rectangular coordinates that represents the result of the multiplication.

multiply

@Nonnull
public static Rectangular multiply(double left,
                                             @Nonnull
                                             Rectangular right)

Multiplies a scalar by a specified set of Rectangular coordinates.

Parameters:

left - The multiplicand, or value which is to be multiplied by right.

right - The multiplier, or value which is to multiply left.

Returns:

A set of Rectangular coordinates that represents the result of the multiplication.

divide

@Nonnull
public static Rectangular divide(@Nonnull
                                           Rectangular left,
                                           double right)

Divides a specified set of Rectangular coordinates by a scalar.

Parameters:

left - The dividend, or value which is to be divided by right.

right - The divisor, or value which is to divide left.

Returns:

A set of Rectangular coordinates that represents the result of the division.

add

@Nonnull
public static Rectangular add(@Nonnull
                                        Rectangular left,
                                        @Nonnull
                                        Rectangular right)

Adds a specified set of Rectangular coordinates to another specified set of Cartesian coordinates.

Parameters:

left - The augend, or value to which right is to be added.

right - The addend, or value which is to be added to left.

Returns:

A set of Rectangular coordinates that represents the result of the addition.

subtract

@Nonnull
public static Rectangular subtract(@Nonnull
                                             Rectangular left,
                                             @Nonnull
                                             Rectangular right)

Subtracts a specified set of Rectangular coordinates from another specified set of Rectangular coordinates.

Parameters:

left - The minuend, or value from which right is to be subtracted.

right - The subtrahend, or value which is to be subtracted from left.

Returns:

A set of Rectangular coordinates that represents the result of the subtraction.

negate

@Nonnull
public static Rectangular negate(@Nonnull
                                           Rectangular coordinates)

Negates the specified set of Rectangular coordinates, yielding a new set of Rectangular coordinates.

Parameters:

coordinates - The set of coordinates.

Returns:

The result of negating the elements of the original set of Rectangular coordinates.

rotate

@Nonnull
public final Rectangular rotate(double angle)

Produces a set of Rectangular coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided angle.

This type of rotation is sometimes referred to as an "alias rotation".

Parameters:

angle - The angle of rotation.

Returns:

A set of Rectangular coordinates which is the result of the rotation.

getLength

public final int getLength()

Gets the number of elements in this set of coordinates.

get

public final double get(int index)

Gets the value of the specified element with index of 0 and 1 corresponding to the coordinates X (get), and Y (get).

Parameters:

index - The index to retrieve.

Returns:

The coordinate associated with the specified index.

Throws:

ArgumentOutOfRangeException - Thrown when index is less than 0 or greater than or equal to Length (get).

equals

public boolean equals(Object obj)

Indicates whether another object is exactly equal to this instance.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this instance.

Returns:

true if obj is an instance of this type and represents the same value as this instance; otherwise false.

See Also:

Object.hashCode(), HashMap

equalsType

public final boolean equalsType(@Nonnull
                                Rectangular other)

Indicates whether another instance of this type is exactly equal to this instance.

Specified by:

equalsType in interface IEquatable<Rectangular>

Parameters:

other - The instance to compare to this instance.

Returns:

true if other represents the same value as this instance; otherwise false.

equalsEpsilon

public final boolean equalsEpsilon(@Nonnull
                                   Rectangular other,
                                   double epsilon)

Indicates whether each coordinate value of another instance of this type is within the required tolerance of the corresponding coordinate value of this instance.

Specified by:

equalsEpsilon in interface IEquatableEpsilon<Rectangular>

Parameters:

other - The set of Rectangular coordinates to compare to this instance.

epsilon - The limit at which the absolute differences between the coordinate values will not be considered equal.

Returns:

true if the absolute differences are less than or equal to epsilon; otherwise false.

hashCode

public int hashCode()

Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.

Overrides:

hashCode in class Object

Returns:

A hash code for the current object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

public String toString()

Returns the string representation of the value of this instance.

Overrides:

toString in class Object

Returns:

A string that represents the value of this instance in the form "X, Y".

equals

public static boolean equals(@Nonnull
                             Rectangular left,
                             @Nonnull
                             Rectangular right)

Returns true if the two instances are exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left represents the same value as right; otherwise false.

notEquals

public static boolean notEquals(@Nonnull
                                Rectangular left,
                                @Nonnull
                                Rectangular right)

Returns true if the two instances are not exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left does not represent the same value as right; otherwise false.

getMagnitude

public final double getMagnitude()

Gets the magnitude of this instance.

getMagnitudeSquared

public final double getMagnitudeSquared()

Gets the square of the Magnitude (get) of this instance.

getHasZeroMagnitude

public final boolean getHasZeroMagnitude()

Gets a value indicating whether the Magnitude (get) of this instance is zero.

getIsUndefined

public final boolean getIsUndefined()

Gets a value indicating whether or not any of the coordinates for this instance have the value Double.NaN.

normalize

@Nonnull
public final UnitRectangular normalize()

Forms a set of UnitRectangular coordinates from this instance.

The normalization of the rectilinear coordinate pair is accomplished in the usual way. It should be noted that this does not guarantee a result whose magnitude will be 1.0 in cases where an individual component underflows upon squaring.

Returns:

The resulting set of UnitRectangular coordinates.

Throws:

ArithmeticException - The magnitude of the provided coordinates must not be zero.

NotFiniteNumberException - The magnitude of the provided coordinates must not be infinite.

normalize

@Nonnull
public final UnitRectangular normalize(@Nonnull
                                                 double[] magnitude)

Forms a set of UnitRectangular coordinates from this instance and returns the Magnitude (get) of the original instance in the provided parameter.

The normalization of the rectilinear coordinate pair is accomplished in the usual way. It should be noted that this does not guarantee a result whose magnitude will be 1.0 in cases where an individual component underflows upon squaring.

Parameters:

magnitude - On input, an array with one element. On return, the array is populated with the magnitude of the original set of Rectangular coordinates.

Returns:

The resulting set of UnitRectangular coordinates.

Throws:

ArithmeticException - The magnitude of the provided coordinates must not be zero.

NotFiniteNumberException - The magnitude of the provided coordinates must not be infinite.

toRectangular

@Nonnull
public static Rectangular toRectangular(@Nonnull
                                                  UnitRectangular coordinates)

Converts a set of UnitRectangular coordinates to a set of Rectangular coordinates.

Parameters:

coordinates - The set of UnitRectangular coordinates.

Returns:

The resulting set of Rectangular coordinates.