agi.foundation.coordinates

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

Class UnitRectangular

java.lang.Object

agi.foundation.coordinates.UnitRectangular

All Implemented Interfaces:

IEquatable<UnitRectangular>, ImmutableValueType, ValueType, IEquatableEpsilon<UnitRectangular>

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

A set of rectilinear 2-dimensional coordinates with unit magnitude.

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.

The corresponding 3-dimensional coordinates are UnitCartesian coordinates.

Constructor Summary

Constructors

Constructor and Description
UnitRectangular() Initializes a new instance.
UnitRectangular(double clock) Initializes a set of UnitRectangular coordinates from the provided polar coordinates.
UnitRectangular(double[] elements) Initializes a set of UnitRectangular coordinates from the first 2 consecutive elements in the provided array.
UnitRectangular(double[] elements, int startIndex) Initializes a set of UnitRectangular coordinates from 2 consecutive elements in the provided array.
UnitRectangular(double x, double y) Initializes a set of UnitRectangular coordinates from the provided values.
UnitRectangular(double x, double y, double[] magnitude) Initializes a set of UnitRectangular coordinates from the provided values.
UnitRectangular(Rectangular coordinates) Initializes a set of UnitRectangular coordinates from the provided set of Rectangular 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, UnitRectangular right) Adds a specified set of UnitRectangular coordinates to a specified set of Rectangular coordinates.
Rectangular	add(UnitRectangular other) Adds the specified set of UnitRectangular coordinates to this instance.
static Rectangular	add(UnitRectangular left, Rectangular right) Adds a specified set of UnitRectangular coordinates to a specified set of Rectangular coordinates.
static Rectangular	add(UnitRectangular left, UnitRectangular right) Adds a specified set of UnitRectangular coordinates to another specified set of UnitRectangular coordinates.
double	angleBetween(UnitRectangular other) Determines the angle in radians between the specified set of UnitRectangular coordinates and this instance.
Rectangular	divide(double scalar) Divides this instance by a scalar.
static Rectangular	divide(UnitRectangular left, double right) Divides a specified set of UnitRectangular coordinates by a scalar.
double	dot(Rectangular other) Forms the dot product of the specified set of Rectangular coordinates with this instance.
double	dot(UnitRectangular other) Forms the dot product of the specified set of UnitRectangular coordinates with this instance.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
static boolean	equals(UnitRectangular left, UnitRectangular right) Returns true if the two instances are exactly equal.
boolean	equalsEpsilon(UnitRectangular 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(UnitRectangular 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	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.
UnitRectangular	getMostOrthogonalAxis() Gets the axis which is most orthogonal to this instance.
UnitRectangular	getMostParallelAxis() Gets the axis which is most parallel to this instance.
static UnitRectangular	getUndefined() Gets a set of UnitRectangular coordinates with values of Double.NaN.
static UnitRectangular	getUnitX() Gets a set of UnitRectangular coordinates representing the x-axis.
static UnitRectangular	getUnitY() Gets a set of UnitRectangular coordinates representing the y-axis.
double	getX() Gets the linear coordinate along the positive x-axis.
double	getY() Gets the linear coordinate along the positive y-axis.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
UnitRectangular	invert() Inverts this instance.
Rectangular	multiply(double scalar) Multiplies this instance by a scalar.
static Rectangular	multiply(double left, UnitRectangular right) Multiplies a scalar by a specified set of UnitRectangular coordinates.
static Rectangular	multiply(UnitRectangular left, double right) Multiplies a specified set of UnitRectangular coordinates by a scalar.
static UnitRectangular	negate(UnitRectangular coordinates) Negates the specified UnitRectangular, yielding a new UnitRectangular.
static boolean	notEquals(UnitRectangular left, UnitRectangular right) Returns true if the two instances are not exactly equal.
UnitRectangular	rotate(double angle) Produces a set of UnitRectangular 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, UnitRectangular right) Subtracts a specified set of UnitRectangular coordinates from a specified set of Rectangular coordinates.
Rectangular	subtract(UnitRectangular other) Subtracts the specified set of UnitRectangular coordinates from this instance.
static Rectangular	subtract(UnitRectangular left, Rectangular right) Subtracts a specified set of Rectangular coordinates from a specified set of UnitRectangular coordinates.
static Rectangular	subtract(UnitRectangular left, UnitRectangular right) Subtracts a specified set of UnitRectangular coordinates from another specified set of UnitRectangular 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

UnitRectangular

public UnitRectangular()

Initializes a new instance.

UnitRectangular

public UnitRectangular(double x,
                       double y)

Initializes a set of UnitRectangular coordinates from the provided values.

Parameters:

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

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

Throws:

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

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

UnitRectangular

public UnitRectangular(double x,
                       double y,
                       @Nonnull
                       double[] magnitude)

Initializes a set of UnitRectangular coordinates from the provided values.

Parameters:

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

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

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

Throws:

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

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

UnitRectangular

public UnitRectangular(@Nonnull
                       Rectangular coordinates)

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

Parameters:

coordinates - The set of Rectangular coordinates.

Throws:

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

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

UnitRectangular

public UnitRectangular(double clock)

Initializes a set of UnitRectangular coordinates from the provided polar coordinates.

Parameters:

clock - The angular coordinate lying in the xy-plane measured from the positive x-axis and toward the positive y-axis.

UnitRectangular

public UnitRectangular(@Nonnull
                       double[] elements)

Initializes a set of UnitRectangular 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.

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

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

UnitRectangular

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

Initializes a set of UnitRectangular 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.

ArithmeticException - Thrown when the magnitude of the provided coordinates are zero.

NotFiniteNumberException - Thrown when the magnitude of the provided coordinates is infinite.

Method Detail

getUndefined

@Nonnull
public static UnitRectangular getUndefined()

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

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

getUnitX

@Nonnull
public static UnitRectangular getUnitX()

Gets a set of UnitRectangular coordinates representing the x-axis.

getUnitY

@Nonnull
public static UnitRectangular getUnitY()

Gets a set of UnitRectangular coordinates representing the y-axis.

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 UnitRectangular invert()

Inverts this instance.

Returns:

A set of UnitRectangular 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.

add

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

Adds the specified set of UnitRectangular 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.

subtract

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

Subtracts the specified set of UnitRectangular 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.

dot

public final double dot(@Nonnull
                        UnitRectangular other)

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

Parameters:

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

Returns:

A double that represents the result of the product.

multiply

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

Multiplies a specified set of UnitRectangular 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
                                             UnitRectangular right)

Multiplies a scalar by a specified set of UnitRectangular 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
                                           UnitRectangular left,
                                           double right)

Divides a specified set of UnitRectangular 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
                                        UnitRectangular left,
                                        @Nonnull
                                        UnitRectangular right)

Adds a specified set of UnitRectangular coordinates to another specified set of UnitRectangular 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.

add

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

Adds a specified set of UnitRectangular coordinates to a specified set of Rectangular 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.

add

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

Adds a specified set of UnitRectangular coordinates to a specified set of Rectangular 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
                                             UnitRectangular left,
                                             @Nonnull
                                             UnitRectangular right)

Subtracts a specified set of UnitRectangular coordinates from another specified set of UnitRectangular 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.

subtract

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

Subtracts a specified set of Rectangular coordinates from a specified set of UnitRectangular 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.

subtract

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

Subtracts a specified set of UnitRectangular coordinates from a 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 UnitRectangular negate(@Nonnull
                                               UnitRectangular coordinates)

Negates the specified UnitRectangular, yielding a new UnitRectangular.

Parameters:

coordinates - The set of coordinates.

Returns:

The result of negating the elements of the original UnitCartesian.

rotate

@Nonnull
public final UnitRectangular rotate(double angle)

Produces a set of UnitRectangular 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 UnitRectangular coordinates which is the result of the rotation.

getMostOrthogonalAxis

@Nonnull
public final UnitRectangular getMostOrthogonalAxis()

Gets the axis which is most orthogonal to this instance.

getMostParallelAxis

@Nonnull
public final UnitRectangular getMostParallelAxis()

Gets the axis which is most parallel to this instance.

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
                                UnitRectangular other)

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

Specified by:

equalsType in interface IEquatable<UnitRectangular>

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
                                   UnitRectangular 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<UnitRectangular>

Parameters:

other - The set of UnitRectangular 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
                             UnitRectangular left,
                             @Nonnull
                             UnitRectangular 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
                                UnitRectangular left,
                                @Nonnull
                                UnitRectangular 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.

getIsUndefined

public final boolean getIsUndefined()

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

angleBetween

public final double angleBetween(@Nonnull
                                 UnitRectangular other)

Determines the angle in radians between the specified set of UnitRectangular coordinates and this instance.

Parameters:

other - The set of UnitRectangular coordinates to evaluate.

Returns:

A double that represents the angle in radians between the two instances.