com.programix.math
Class LongRange

java.lang.Object
  com.programix.math.LongRange

All Implemented Interfaces:

Serializable, Cloneable, Comparable<LongRange>

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

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

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

Author:

Paul Hyde

See Also:

IntegerRange, DecimalRange, Long, NumberTools, Serialized Form

Field Summary

static LongRange	BOTH_OPEN This LongRange has both an undefined start and an undefined end.
static Comparator<LongRange>	HIGHEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "highest" first.
static Comparator<LongRange>	LOWEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "lowest" first.
static LongRange	MIN_TO_MAX_LONG This LongRange runs from Long.MIN_VALUE to Long.MAX_VALUE.
static LongRange	NEGATIVE This LongRange covers all negative values with an undefined start and an end of "-1".
static LongRange	NON_NEGATIVE This LongRange covers all non-negative values with a start of "0" and an undefined end.
static LongRange	NON_POSITIVE This LongRange covers all non-positive values with an undefined start and an end of "0".
static Long	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 LongRange	POSITIVE This LongRange covers all positive values with a start of "1" and an undefined end.

Constructor Summary

LongRange(long start, long end)
Creates a new instance with the specified start and end values.

LongRange(Long start, Long end)
Creates a new instance with the specified start and end values.

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

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

This LongRange has both an undefined start and an undefined end. Although similar to MIN_TO_MAX_LONG, this range has an undefined start and an undefined end. This is a shareable instance as all instances of LongRange 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 LongRange has both an undefined start and an undefined end.

MIN_TO_MAX_LONG

public static final LongRange MIN_TO_MAX_LONG

This LongRange runs from Long.MIN_VALUE to Long.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 LongRange 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 LongRange POSITIVE

This LongRange 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 LongRange are immutable.

See Also:

NEGATIVE, NON_NEGATIVE, NON_POSITIVE

NON_NEGATIVE

public static final LongRange NON_NEGATIVE

This LongRange 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 LongRange are immutable.

See Also:

POSITIVE, NEGATIVE, NON_POSITIVE

NON_POSITIVE

public static final LongRange NON_POSITIVE

This LongRange 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 LongRange are immutable.

See Also:

POSITIVE, NEGATIVE, NON_NEGATIVE

NEGATIVE

public static final LongRange NEGATIVE

This LongRange 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 LongRange are immutable.

See Also:

POSITIVE, NON_NEGATIVE, NON_POSITIVE

LOWEST_FIRST_COMPARATOR

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

LongRange

public LongRange(Long start,
                 Long 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:

LongRange(Value, Value), LongRange(String, String)

LongRange

public LongRange(long start,
                 long end)
          throws IllegalArgumentException

Creates a new instance with the specified start and end values. Open ends can not be specified with this constructor, use LongRange(Long, Long) 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:

LongRange(Long, Long), LongRange(Value, Value), LongRange(String, String)

LongRange

public LongRange(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 Long (see NumberTools.parseLongLenient(String)).

See Also:

LongRange(Long, Long), LongRange(long, long), LongRange(Value, Value), NumberTools.parseLongLenient(String)

LongRange

public LongRange(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 Long (see Value.getLongNumberOrNull()).

See Also:

LongRange(Long, Long), LongRange(long, long), LongRange(String, String), Value.getLongNumberOrNull()

Method Detail

createWithOpenStart

public static LongRange createWithOpenStart(Long 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 LongRange createWithOpenEnd(Long start)

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

Parameters:

start - the start of the value range.

setStart

public LongRange setStart(Long 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:

LongRange(Long, Long)

setStart

public LongRange setStart(long 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:

LongRange(long, long)

setStart

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

LongRange(String, String)

setStart

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

LongRange(Value, Value)

setEnd

public LongRange setEnd(Long 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:

LongRange(Long, Long)

setEnd

public LongRange setEnd(long 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:

LongRange(long, long)

setEnd

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

LongRange(String, String)

setEnd

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

LongRange(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 Long 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 Long 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(Long value)

Returns true if the specified Long 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(long value)

Returns true if the specified long 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 Long forceIntoRange(Long value)
                    throws IllegalArgumentException

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

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

Compares this instance to otherRange as defined by LOWEST_FIRST_COMPARATOR.

Specified by:

compareTo in interface Comparable<LongRange>

Throws:

IllegalArgumentException - if null is passed.

equals

public boolean equals(LongRange otherLong)

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