com.programix.math
Class DecimalRange

java.lang.Object
  com.programix.math.DecimalRange

All Implemented Interfaces:

Serializable, Cloneable, Comparable<DecimalRange>

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

Immutable encapsulation of a range of decimal values as expressed by a starting BigDecimal and an ending BigDecimal. Either the starting value or the ending value or both can be null. If you need a value span that does not need fractional information, see IntegerRange.

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

Author:

Paul Hyde

See Also:

DecimalTools, BigDecimal, IntegerRange, Serialized Form

Field Summary

static DecimalRange	BOTH_OPEN This DecimalRange has both an undefined start and an undefined end.
static Comparator<DecimalRange>	HIGHEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "highest" first.
static Comparator<DecimalRange>	LOWEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "lowest" first.
static DecimalRange	NON_NEGATIVE This DecimalRange covers all non-negative values with a start of "0.0" and an undefined end.
static DecimalRange	NON_POSITIVE This DecimalRange covers all non-positive values with an undefined start and an end of "0.0".
static BigDecimal	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).

Constructor Summary

DecimalRange(BigDecimal start, BigDecimal end)
Creates a new instance with the specified start and end values.

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

DecimalRange(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(DecimalRange otherRange) Compares this instance to otherRange as defined by LOWEST_FIRST_COMPARATOR.
boolean	contains(BigDecimal value) Returns true if the specified BigDecimal falls within this range (inclusive of both endpoints).
static DecimalRange	createWithOpenEnd(BigDecimal start) Creates a new instance with an open end and the specified start value.
static DecimalRange	createWithOpenStart(BigDecimal end) Creates a new instance with an open start and the specified end value.
boolean	equals(DecimalRange otherBigDecimal) 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.
BigDecimal	forceIntoRange(BigDecimal value) Forces the specified BigDecimal into this range.
BigDecimal	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.
BigDecimal	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()
DecimalRange	setEnd(BigDecimal newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
DecimalRange	setEnd(String newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
DecimalRange	setEnd(Value newEnd) Returns a new instance with the specified newEnd value and this instance's start value.
DecimalRange	setStart(BigDecimal newStart) Returns a new instance with the specified newStart value and this instance's end value.
DecimalRange	setStart(String newStart) Returns a new instance with the specified newStart value and this instance's end value.
DecimalRange	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 BigDecimal 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 DecimalRange BOTH_OPEN

This DecimalRange has both an undefined start and an undefined end. This is a shareable instance as all instances of DecimalRange 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 DecimalRange has both an undefined start and and undefined end.

NON_NEGATIVE

public static final DecimalRange NON_NEGATIVE

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

NON_POSITIVE

public static final DecimalRange NON_POSITIVE

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

LOWEST_FIRST_COMPARATOR

public static final Comparator<DecimalRange> 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<DecimalRange> 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

DecimalRange

public DecimalRange(BigDecimal start,
                    BigDecimal 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:

DecimalRange(Value, Value), DecimalRange(String, String)

DecimalRange

public DecimalRange(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 BigDecimal (see DecimalTools.parseBigDecimal(String)).

See Also:

DecimalRange(BigDecimal, BigDecimal), DecimalRange(Value, Value), DecimalTools.parseBigDecimal(String)

DecimalRange

public DecimalRange(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 BigDecimal (see Value.getBigDecimalOrNull()).

See Also:

DecimalRange(BigDecimal, BigDecimal), DecimalRange(String, String), Value.getBigDecimalOrNull()

Method Detail

createWithOpenStart

public static DecimalRange createWithOpenStart(BigDecimal 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 DecimalRange createWithOpenEnd(BigDecimal start)

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

Parameters:

start - the start of the value range.

setStart

public DecimalRange setStart(BigDecimal 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:

DecimalRange(BigDecimal, BigDecimal)

setStart

public DecimalRange 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:

DecimalRange(String, String)

setStart

public DecimalRange 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:

DecimalRange(Value, Value)

setEnd

public DecimalRange setEnd(BigDecimal 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:

DecimalRange(BigDecimal, BigDecimal)

setEnd

public DecimalRange 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:

DecimalRange(String, String)

setEnd

public DecimalRange 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:

DecimalRange(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 BigDecimal 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 BigDecimal 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(BigDecimal value)

Returns true if the specified BigDecimal 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.

forceIntoRange

public BigDecimal forceIntoRange(BigDecimal value)
                          throws IllegalArgumentException

Forces the specified BigDecimal into this range. If the specified value is contained with this range (see contains(BigDecimal)), 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.

compareTo

public int compareTo(DecimalRange otherRange)
              throws IllegalArgumentException

Compares this instance to otherRange as defined by LOWEST_FIRST_COMPARATOR.

Specified by:

compareTo in interface Comparable<DecimalRange>

Throws:

IllegalArgumentException - if null is passed.

equals

public boolean equals(DecimalRange otherBigDecimal)

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