org.kynosarges.tektosyne.geometry

Class RectI

java.lang.Object

org.kynosarges.tektosyne.geometry.RectI

public final class RectI
extends java.lang.Object

Represents a rectangular region in two-dimensional space, using Integer coordinates. RectI contains two immutable PointI locations, defining the opposite corners of a rectangle. Use RectD to represent rectangles with Double coordinates.

Field Summary

Fields

Modifier and Type	Field and Description
static RectI	EMPTY An empty read-only RectI.
PointI	max The greatest coordinates within the RectI.
PointI	min The smallest coordinates within the RectI.

Constructor Summary

Constructors

Constructor and Description
RectI() Creates a RectI with all coordinates set to zero.
RectI(int minX, int minY, int maxX, int maxY) Creates a RectI with the specified Integer coordinates.
RectI(PointI min, PointI max) Creates a RectI with the specified PointI coordinates.

Method Summary

Modifier and Type	Method and Description
static RectI	circumscribe(PointI... points) Circumscribes a RectI around the specified PointI coordinates.
boolean	contains(int x, int y) Determines whether the RectI contains the specified Integer coordinates.
boolean	contains(PointI point) Determines whether the RectI contains the specified PointI coordinates.
boolean	contains(RectI rect) Determines whether the RectI entirely contains the specified instance.
boolean	containsOpen(int x, int y) Determines whether the RectI contains the specified Integer coordinates, excluding the x- and y-coordinates of max.
boolean	containsOpen(PointI point) Determines whether the RectI contains the specified PointD coordinates, excluding the x- and y-coordinates of max.
PointI	distanceVector(PointI q) Finds the distance vector from the specified PointI coordinates to the nearest edges of the RectI.
boolean	equals(java.lang.Object obj) Compares the specified Object to this RectI instance.
static RectI[]	fromInts(int... rects) Converts the specified Integer array to a RectI array.
int	hashCode() Returns a hash code for the RectI.
long	height() Gets the height the RectI.
RectI	intersect(RectI rect) Finds the intersection of the RectI with the specified instance.
boolean	intersectsWith(RectI rect) Determines whether the RectI intersects with the specified instance.
RectLocation	locate(PointI q) Determines the location of the specified PointI relative to the RectI.
RectI	offset(int x, int y) Offsets the RectI by the specified Integer distances.
RectI	offset(PointI vector) Offsets the RectI by the specified PointI vector.
static int[]	toInts(RectI... rects) Converts the specified RectI array to an Integer array.
RectD	toRectD() Converts the RectI to a RectD.
java.lang.String	toString() Returns a String representation of the RectI.
RectI	union(RectI rect) Finds the union of the RectI with the specified instance.
long	width() Gets the width the RectI.

Methods inherited from class java.lang.Object

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

Field Detail

min

public final PointI min

The smallest coordinates within the RectI. Both dimensions are equal to or less than the corresponding max dimensions.

max

public final PointI max

The greatest coordinates within the RectI. Both dimensions are equal to or greater than the corresponding min dimensions.

EMPTY

public static final RectI EMPTY

An empty read-only RectI. min and max are both set to PointI.EMPTY.

Constructor Detail

RectI

public RectI()

Creates a RectI with all coordinates set to zero. min and max are both set to PointI.EMPTY.

RectI

public RectI(int minX,
             int minY,
             int maxX,
             int maxY)

Creates a RectI with the specified Integer coordinates.

Parameters:

minX - the smallest x-coordinate within the RectI

minY - the smallest y-coordinate within the RectI

maxX - the greatest x-coordinate within the RectI

maxY - the greatest y-coordinate within the RectI

Throws:

java.lang.IllegalArgumentException - if maxX is less than minX, or maxY is less than minY

RectI

public RectI(PointI min,
             PointI max)

Creates a RectI with the specified PointI coordinates.

Parameters:

min - the smallest coordinates within the RectI

max - the greatest coordinates within the RectI

Throws:

java.lang.IllegalArgumentException - if any dimension of max is less than the corresponding dimension of min

java.lang.NullPointerException - if min or max is null

Method Detail

circumscribe

public static RectI circumscribe(PointI... points)

Circumscribes a RectI around the specified PointI coordinates. Sets both dimensions of min to the smallest coordinates, and both dimensions of max to the greatest coordinates, found among any points.

Parameters:

points - an array of PointI coordinates whose bounds to determine

Returns:

the smallest RectI that contains all specified points

Throws:

java.lang.NullPointerException - if points is null or empty, or contains any null elements

contains

public boolean contains(int x,
                        int y)

Determines whether the RectI contains the specified Integer coordinates.

Parameters:

x - the x-coordinate to examine

y - the y-coordinate to examine

Returns:

true if both x and y fall within the range of coordinates defined by min and max, else false

contains

public boolean contains(PointI point)

Determines whether the RectI contains the specified PointI coordinates.

Parameters:

point - the PointI to examine

Returns:

true if both dimensions of point fall within the range of coordinates defined by min and max, else false

Throws:

java.lang.NullPointerException - if point is null

contains

public boolean contains(RectI rect)

Determines whether the RectI entirely contains the specified instance.

Parameters:

rect - the RectI to examine

Returns:

true if both min and max of the specified rect fall within the range coordinates defined by this instance, else false

Throws:

java.lang.NullPointerException - if rect is null

containsOpen

public boolean containsOpen(int x,
                            int y)

Determines whether the RectI contains the specified Integer coordinates, excluding the x- and y-coordinates of max.

Parameters:

x - the x-coordinate to examine

y - the y-coordinate to examine

Returns:

true if both x and y fall within the range of coordinates defined by min (inclusive) and max (exclusive), else false

containsOpen

public boolean containsOpen(PointI point)

Determines whether the RectI contains the specified PointD coordinates, excluding the x- and y-coordinates of max.

Parameters:

point - the PointI to examine

Returns:

true if both dimensions of point fall within the range of coordinates defined by min (inclusive) and max (exclusive), else false

Throws:

java.lang.NullPointerException - if point is null

distanceVector

public PointI distanceVector(PointI q)

Finds the distance vector from the specified PointI coordinates to the nearest edges of the RectI. The returned coordinates are negative if the corresponding dimension of q if less than that of min, and positive if it is greater than max.

Parameters:

q - the PointI to examine

Returns:

a PointI whose dimensions equal zero if they fall within the corresponding dimensions of min and max, else the signed difference to the nearest edge coordinate

Throws:

java.lang.ArithmeticException - if the difference in any dimension overflows Integer

java.lang.NullPointerException - if q is null

fromInts

public static RectI[] fromInts(int... rects)

Converts the specified Integer array to a RectI array. The returned array has a quarter as many elements as the specified rects and retains the same coordinate sequence.

Parameters:

rects - an array containing the coordinates min.x, min.y, max.x, max.y of RectI instances, stored in successive index positions per RectI

Returns:

the RectI array created from rects

Throws:

java.lang.IllegalArgumentException - if the length of rects is not divisible by four, or if any max coordinate is less than the corresponding min coordinate

java.lang.NullPointerException - if rects is null

height

public long height()

Gets the height the RectI. Never negative but may be zero. One less than the actual height if RectI coordinates represent pixels. Coordinates are widened to Long to prevent Integer overflow.

Returns:

the difference between the x-coordinates of max and min

intersect

public RectI intersect(RectI rect)

Finds the intersection of the RectI with the specified instance.

Parameters:

rect - the RectI to intersect with this instance

Returns:

a RectI that contains the intersection of rect with this instance, if any intersection was found, else null

Throws:

java.lang.NullPointerException - if rect is null

intersectsWith

public boolean intersectsWith(RectI rect)

Determines whether the RectI intersects with the specified instance.

Parameters:

rect - the RectI to examine

Returns:

true if rect shares any coordinates with this instance, else false

Throws:

java.lang.NullPointerException - if rect is null

locate

public RectLocation locate(PointI q)

Determines the location of the specified PointI relative to the RectI.

Parameters:

q - the PointI coordinates to examine

Returns:

a RectLocation indicating the location of q relative to the RectD in each dimension

Throws:

java.lang.NullPointerException - if q is null

offset

public RectI offset(int x,
                    int y)

Offsets the RectI by the specified Integer distances.

Parameters:

x - the horizontal offset applied to the RectI

y - the vertical offset applied to the RectI

Returns:

a RectI whose min and max equal those of the current instance, with x and y added to all corresponding dimensions

Throws:

java.lang.ArithmeticException - if the new coordinates in any dimension overflow Integer

offset

public RectI offset(PointI vector)

Offsets the RectI by the specified PointI vector.

Parameters:

vector - the PointI offset applied to the RectI

Returns:

a RectI whose min and max equal those of the current instance, with vector added to both points

Throws:

java.lang.ArithmeticException - if the new coordinates in any dimension overflow Integer

java.lang.NullPointerException - if vector is null

toInts

public static int[] toInts(RectI... rects)

Converts the specified RectI array to an Integer array. The returned array has four times as many elements as the specified rects and retains the same coordinate sequence.

Parameters:

rects - the RectI array to convert

Returns:

an array containing the coordinates min.x, min.y, max.x, max.y for all rects, stored in successive index positions per RectI

Throws:

java.lang.NullPointerException - if rects or any of its elements is null

toRectD

public RectD toRectD()

Converts the RectI to a RectD.

Returns:

a RectD whose RectD.min and RectD.max points equal the corresponding points of the RectI

union

public RectI union(RectI rect)

Finds the union of the RectI with the specified instance.

Parameters:

rect - the RectI to combine with this instance

Returns:

a RectI that contains the union of rect with this instance

Throws:

java.lang.NullPointerException - if rect is null

width

public long width()

Gets the width the RectI. Never negative but may be zero. One less than the actual width if RectI coordinates represent pixels. Coordinates are widened to Long to prevent Integer overflow.

Returns:

the difference between the y-coordinates of max and min

equals

public boolean equals(java.lang.Object obj)

Compares the specified Object to this RectI instance.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the Object to compare to this instance

Returns:

true if obj is not null and a RectI instance whose min and max equal those of this instance, else false

hashCode

public int hashCode()

Returns a hash code for the RectI.

Overrides:

hashCode in class java.lang.Object

Returns:

an Integer hash code for the RectI

toString

public java.lang.String toString()

Returns a String representation of the RectI.

Overrides:

toString in class java.lang.Object

Returns:

a String containing the values of min and max