com.programix.math
Class IntegerRange

java.lang.Object
  com.programix.math.IntegerRange

All Implemented Interfaces:

Serializable, Cloneable, Comparable<IntegerRange>

public final class IntegerRange
extends Object
implements Serializable, Comparable<IntegerRange>, Cloneable

Immutable encapsulation of a range of integer values as expressed by a starting Integer and an ending Integer. If you need a value span with a larger range, see LongRange. Either the starting value or the ending value or both can be null. If you need a value span that includes fractional information, see DecimalRange.

The Integer class itself and the utility NumberTools have handy utilities for formatting and parsing Integer instances to and from more human-readable Strings.

Author:

Paul Hyde

See Also:

LongRange, DecimalRange, Integer, NumberTools, Serialized Form

Field Summary

static IntegerRange	BOTH_OPEN This IntegerRange has both an undefined start and an undefined end.
static Comparator<IntegerRange>	HIGHEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "highest" first.
static Comparator<IntegerRange>	LOWEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "lowest" first.
static IntegerRange	MIN_TO_MAX_INT This IntegerRange runs from Integer.MIN_VALUE to Integer.MAX_VALUE.
static IntegerRange	NEGATIVE This IntegerRange covers all negative values with an undefined start and an end of "-1".
static IntegerRange	NON_NEGATIVE This IntegerRange covers all non-negative values with a start of "0" and an undefined end.
static IntegerRange	NON_POSITIVE This IntegerRange covers all non-positive values with an undefined start and an end of "0".
static Integer	OPEN This constant can be used to specify that either the start or end of of the range is "open" (that is, it is not defined and can be considered to stretch out to infinity).
static IntegerRange	POSITIVE This IntegerRange covers all positive values with a start of "1" and an undefined end.

Constructor Summary

IntegerRange(Integer start, Integer end)
Creates a new instance with the specified start and end values.

IntegerRange(int start, int end)
Creates a new instance with the specified start and end values.

IntegerRange(String start, String end)
Creates a new instance with the specified start and end values.

IntegerRange(Value start, Value end)
Creates a new instance with the specified start and end values.

Method Summary

Object	clone() Simply returns a reference to this instance.
int	compareTo(IntegerRange otherRange) Compares this instance to otherRange as defined by LOWEST_FIRST_COMPARATOR.
boolean	contains(int value) Returns true if the specified int falls within this range (inclusive of both endpoints).
boolean	contains(Integer value) Returns true if the specified Integer falls within this range (inclusive of both endpoints).
static IntegerRange	createWithOpenEnd(Integer start) Creates a new instance with an open end and the specified start value.
static IntegerRange	createWithOpenStart(Integer end) Creates a new instance with an open start and the specified end value.
boolean	equals(IntegerRange otherInteger) Returns true if this instance's start and end values exactly match the start and end values of the passed instance.
boolean	equals(Object obj) Returns true if this instance's start and end values exactly match the start and end values of the passed instance.
int	forceIntoRange(int value) Forces the specified int into this range.
Integer	forceIntoRange(Integer value) Forces the specified Integer into this range.
Integer	getEnd() Returns the end of this range.
String	getEndString() Returns the end of this range as a String.
Value	getEndValue() Returns the end of this range as a Value.
Integer	getStart() Returns the start of this range.
String	getStartString() Returns the start of this range as a String.
Value	getStartValue() Returns the start of this range as a Value.
boolean	hasDefinedEnd() Returns true if this range has a defined end value.
boolean	hasDefinedStart() Returns true if this range has a defined start value.
int	hashCode()
IntegerRange	setEnd(int newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
IntegerRange	setEnd(Integer newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
IntegerRange	setEnd(String newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
IntegerRange	setEnd(Value newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
IntegerRange	setStart(int newStart) Returns a new instance with the specified newStart value and this instance's end value.
IntegerRange	setStart(Integer newStart) Returns a new instance with the specified newStart value and this instance's end value.
IntegerRange	setStart(String newStart) Returns a new instance with the specified newStart value and this instance's end value.
IntegerRange	setStart(Value newStart) Returns a new instance with the specified newStart value and this instance's end value.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

OPEN

public static final Integer OPEN

This constant can be used to specify that either the start or end of of the range is "open" (that is, it is not defined and can be considered to stretch out to infinity).

BOTH_OPEN

public static final IntegerRange BOTH_OPEN

This IntegerRange has both an undefined start and an undefined end. Although similar to MIN_TO_MAX_INT, this range has an undefined start and an undefined end. This is a shareable instance as all instances of IntegerRange are immutable. In addition, there is no need to create any other instances that have both ends open (although is it permissible to create those instances). This IntegerRange has both an undefined start and an undefined end.

See Also:

MIN_TO_MAX_INT

MIN_TO_MAX_INT

public static final IntegerRange MIN_TO_MAX_INT

This IntegerRange runs from Integer.MIN_VALUE to Integer.MAX_VALUE. Although similar to BOTH_OPEN, this range has a defined start and a defined end. This is a shareable instance as all instances of IntegerRange are immutable. In addition, there is no need to create any other instances that cover this full range (although is it permissible to create those instances).

POSITIVE

public static final IntegerRange POSITIVE

This IntegerRange covers all positive values with a start of "1" and an undefined end. It does not include zero (zero is neither positive or negative). This is a shareable instance as all instances of IntegerRange are immutable.

See Also:

NEGATIVE, NON_NEGATIVE, NON_POSITIVE

NON_NEGATIVE

public static final IntegerRange NON_NEGATIVE

This IntegerRange covers all non-negative values with a start of "0" and an undefined end. It includes zero and all of the positive numbers. This is a shareable instance as all instances of IntegerRange are immutable.

See Also:

POSITIVE, NEGATIVE, NON_POSITIVE

NON_POSITIVE

public static final IntegerRange NON_POSITIVE

This IntegerRange covers all non-positive values with an undefined start and an end of "0". It includes zero and all of the negative numbers. This is a shareable instance as all instances of IntegerRange are immutable.

See Also:

POSITIVE, NEGATIVE, NON_NEGATIVE

NEGATIVE

public static final IntegerRange NEGATIVE

This IntegerRange covers all negative values with an undefined start and an end of "-1". It does not include zero (zero is neither positive or negative). This is a shareable instance as all instances of IntegerRange are immutable.

See Also:

POSITIVE, NON_NEGATIVE, NON_POSITIVE

LOWEST_FIRST_COMPARATOR

public static final Comparator<IntegerRange> LOWEST_FIRST_COMPARATOR

Compares two ranges placing ranges that are considered "lowest" first. Open start values are considered to come before defined start values. Open end values are considered to come after defined end values. The following are listed in the order that would result by using this Comparator:

Also see HIGHEST_FIRST_COMPARATOR as it is not simply the reverse of this comparator.

For additional permutations, see NullFirstComparator, NullLastComparator, and ReverseComparator.

HIGHEST_FIRST_COMPARATOR

public static final Comparator<IntegerRange> HIGHEST_FIRST_COMPARATOR

Compares two ranges placing ranges that are considered "highest" first. Open end values are considered to come before defined end values. Open start values are considered to come after defined start values. The following are listed in the order that would result by using this Comparator:

Also see LOWEST_FIRST_COMPARATOR as it is not simply the reverse of this comparator.

For additional permutations, see NullFirstComparator, NullLastComparator, and ReverseComparator.

Constructor Detail

IntegerRange

public IntegerRange(Integer start,
                    Integer end)
             throws IllegalArgumentException

Creates a new instance with the specified start and end values. The constant OPEN (or null) can be used to indicate that one end or the other is open-ended. Both the start and the end can be open, and if you prefer, there is a shared, immutable instance that can be used instead: BOTH_OPEN.

Parameters:

start - the beginning of the value range. Use OPEN or null to indicate that the range is open-ended and has no starting value (negative infinity).

end - the ending of the value range. Use OPEN or null to indicate that the range is open-ended and has no ending value (positive infinity).

Throws:

IllegalArgumentException - if the start value is greater than the end value.

See Also:

IntegerRange(Value, Value), IntegerRange(String, String)

IntegerRange

public IntegerRange(int start,
                    int end)
             throws IllegalArgumentException

Creates a new instance with the specified start and end values. Open ends can not be specified with this constructor, use IntegerRange(Integer, Integer) if open ends are needed.

Parameters:

start - the beginning of the value range.

end - the ending of the value range.

Throws:

IllegalArgumentException - if the start value is greater than the end value.

See Also:

IntegerRange(Integer, Integer), IntegerRange(Value, Value), IntegerRange(String, String)

IntegerRange

public IntegerRange(String start,
                    String end)
             throws IllegalArgumentException

Creates a new instance with the specified start and end values. You can use null or an empty string to indicate that one end or the other (or both) is open-ended.

Parameters:

start - the beginning of the value range. Use null or an empty string to indicate that the range is open-ended and has no starting value.

end - the ending of the value range. Use null or an empty string to indicate that the range is open-ended and has no end value.

Throws:

IllegalArgumentException - if the start value is greater than the end value. Or, if one of the String's is not empty and can not be parsed as a Integer (see NumberTools.parseIntLenient(String)).

See Also:

IntegerRange(Integer, Integer), IntegerRange(int, int), IntegerRange(Value, Value), NumberTools.parseIntLenient(String)

IntegerRange

public IntegerRange(Value start,
                    Value end)
             throws IllegalArgumentException

Creates a new instance with the specified start and end values. You can use null for either parameter to indicate that one end or the other (or both) is open-ended. You can also use a Value who's isEmpty() method returns true to indicate that one end or the other (or both) is open-ended.

Parameters:

start - the beginning of the value range. Use null or an empty Value to indicate that the range is open-ended and has no starting value.

end - the ending of the value range. Use null or an empty Value to indicate that the range is open-ended and has no ending value.

Throws:

IllegalArgumentException - if the start value is greater than the end value. Or, if one of the Value's is not empty and can not be parsed as a Integer (see Value.getIntegerNumberOrNull()).

See Also:

IntegerRange(Integer, Integer), IntegerRange(int, int), IntegerRange(String, String), Value.getIntegerNumberOrNull()

Method Detail

createWithOpenStart

public static IntegerRange createWithOpenStart(Integer end)

Creates a new instance with an open start and the specified end value.

Parameters:

end - the end of the value range.

createWithOpenEnd

public static IntegerRange createWithOpenEnd(Integer start)

Creates a new instance with an open end and the specified start value.

Parameters:

start - the start of the value range.

setStart

public IntegerRange setStart(Integer newStart)
                      throws IllegalArgumentException

Returns a new instance with the specified newStart value and this instance's end value.

Parameters:

newStart - the new start value for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start value is greater than the end value.

See Also:

IntegerRange(Integer, Integer)

setStart

public IntegerRange setStart(int newStart)
                      throws IllegalArgumentException

Returns a new instance with the specified newStart value and this instance's end value.

Parameters:

newStart - the new start value for the new instance.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start value is greater than the end value.

See Also:

IntegerRange(int, int)

setStart

public IntegerRange setStart(String newStart)
                      throws IllegalArgumentException

Returns a new instance with the specified newStart value and this instance's end value.

Parameters:

newStart - the new start value for the new instance or null (or empty).

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if newStart is not empty and can't be parsed.

See Also:

IntegerRange(String, String)

setStart

public IntegerRange setStart(Value newStart)
                      throws IllegalArgumentException

Returns a new instance with the specified newStart value and this instance's end value.

Parameters:

newStart - the new start value for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if newStart is not empty and can't be parsed.

See Also:

IntegerRange(Value, Value)

setEnd

public IntegerRange setEnd(Integer newEnd)
                    throws IllegalArgumentException

Returns a new instance with the specified newEnd value and this instance's start value.

Parameters:

newEnd - the new end value for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end.

See Also:

IntegerRange(Integer, Integer)

setEnd

public IntegerRange setEnd(int newEnd)
                    throws IllegalArgumentException

Returns a new instance with the specified newEnd value and this instance's start value.

Parameters:

newEnd - the new end value for the new instance.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end.

See Also:

IntegerRange(int, int)

setEnd

public IntegerRange setEnd(String newEnd)
                    throws IllegalArgumentException

Returns a new instance with the specified newEnd value and this instance's start value.

Parameters:

newEnd - the new end value for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if the end is not empty and can't be parsed.

See Also:

IntegerRange(String, String)

setEnd

public IntegerRange setEnd(Value newEnd)
                    throws IllegalArgumentException

Returns a new instance with the specified newEnd value and this instance's start value.

Parameters:

newEnd - the new end value for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if the end is not empty and can't be parsed.

See Also:

IntegerRange(Value, Value)

hasDefinedStart

public boolean hasDefinedStart()

Returns true if this range has a defined start value. If no start is defined, then this range is open-ended and false is returned.

See Also:

getStart()

getStart

public Integer getStart()

Returns the start of this range. If no starting value was specified, then this range is open-ended and OPEN (null) is returned.

See Also:

hasDefinedStart(), getStartString(), getStartValue()

getStartString

public String getStartString()

Returns the start of this range as a String. If no starting value was specified, then this range is open-ended and null is returned.

See Also:

hasDefinedStart(), getStart(), getStartValue()

getStartValue

public Value getStartValue()

Returns the start of this range as a Value. If no starting value was specified, then this range is open-ended and an empty Value is returned. Unlike most of the other getters, a Value is always returned—null is never returned.

See Also:

hasDefinedStart(), getStart(), getStartString()

hasDefinedEnd

public boolean hasDefinedEnd()

Returns true if this range has a defined end value. If no end is defined, then this range is open-ended and false is returned.

See Also:

getEnd()

getEnd

public Integer getEnd()

Returns the end of this range. If no ending value was specified, then this range is open-ended and OPEN (null) is returned.

See Also:

hasDefinedEnd()

getEndString

public String getEndString()

Returns the end of this range as a String. If no ending value was specified, then this range is open-ended and null is returned.

See Also:

hasDefinedEnd(), getEnd(), getEndValue()

getEndValue

public Value getEndValue()

Returns the end of this range as a Value. If no ending value was specified, then this range is open-ended and an empty Value is returned. Unlike most of the other getters, a Value is always returned—null is never returned.

See Also:

hasDefinedEnd(), getEnd(), getEndString()

contains

public boolean contains(Integer value)

Returns true if the specified Integer falls within this range (inclusive of both endpoints). If null is passed in, then false is always returned (regardless of the values of either endpoint). If this instance has a defined start, but an unknown end, then true is returned if the passed value is greater than or equal to the start. If this instance has a defined end, but an unknown start, then true is returned if the passed value is less than or equal to the end. If this instance has both ends open and the passed parameter is not null, then true is returned.

contains

public boolean contains(int value)

Returns true if the specified int falls within this range (inclusive of both endpoints). If this instance has a defined start, but an unknown end, then true is returned if the passed value is greater than or equal to the start. If this instance has a defined end, but an unknown start, then true is returned if the passed value is less than or equal to the end. If this instance has both ends open, then true is returned.

forceIntoRange

public Integer forceIntoRange(Integer value)
                       throws IllegalArgumentException

Forces the specified Integer into this range. If the specified value is contained with this range (see contains(Integer)), then the passed value is simply returned (no forcing is necessary). If the range has a defined start and the specified value is less than the start, then the start is returned. If the range has a defined end and the specified value is greater than the end, then the end is returned.

Parameters:

value - the value to force into this range.

Returns:

a value that is within this range.

Throws:

IllegalArgumentException - if the specified value is null.

forceIntoRange

public int forceIntoRange(int value)

Forces the specified int into this range. If the specified value is contained with this range (see contains(int)), then the passed value is simply returned (no forcing is necessary). If the range has a defined start and the specified value is less than the start, then the start is returned. If the range has a defined end and the specified value is greater than the end, then the end is returned.

Parameters:

value - the value to force into this range.

Returns:

a value that is within this range.

compareTo

public int compareTo(IntegerRange otherRange)
              throws IllegalArgumentException

Compares this instance to otherRange as defined by LOWEST_FIRST_COMPARATOR.

Specified by:

compareTo in interface Comparable<IntegerRange>

Throws:

IllegalArgumentException - if null is passed.

equals

public boolean equals(IntegerRange otherInteger)

Returns true if this instance's start and end values exactly match the start and end values of the passed instance. If null is passed, false is returned.

equals

public boolean equals(Object obj)

Returns true if this instance's start and end values exactly match the start and end values of the passed instance. If null is passed, false is returned. If a type other than IntegerRange is passed in, false is returned (ClassCastException is not thrown).

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

clone

public Object clone()

Simply returns a reference to this instance. No need to actually clone since objects of this type are immutable.

Overrides:

clone in class Object