T - type of comparable elements of the interval.public class Interval<T extends Comparable<T>> extends Object implements Emptily
S and a total order relation <=
over the elements of S, we define an interval I as a
subset of S such that: given x,y in I such that x <= y we have
that for each s in S if x <= s <= y then s belongs to I.
An interval can be empty, it can have a lower bound value called
inf, it can have an upper bound value called sup,
and it can also be unbounded. The upper and lower bounds can be included
in the interval, in this case we say that the interval is closed, or they may
be excluded from the interval, in this case we say that the interval is open.
This definition can be applied to numbers but it can also be applied to dates, strings, pairs and any other comparable value.
This class provides a Java representation of an interval as described above. It allows some operations on intervals like: union, intersection, subtraction and checks like if two intervals overlaps, if are disjoint, if one includes another, if a given value belongs to the interval, etc.
An interval is immutable. Operations on intervals will create new intervals.
If two intervals are disjoint the method unify(Interval) will throw
a NoSuchIntervalException. For unbounded intervals the methods
getInf() and getSup() may throw a NoSuchElementException.
| Modifier | Constructor and Description |
|---|---|
protected |
Interval()
Default constructor.
|
protected |
Interval(org.nerd4j.utils.math.IntervalLimit<T> inf,
org.nerd4j.utils.math.IntervalLimit<T> sup)
Constructor with parameters.
|
| Modifier and Type | Method and Description |
|---|---|
boolean |
canSubtract(Interval<T> other)
Tells if the given interval can be subtracted from this one.
|
boolean |
canUnify(Interval<T> other)
Tells if this interval can be unified with the given one.
|
static <T extends Comparable<T>> |
closed(T inf,
T sup)
Creates a new closed
Interval with the given limits. |
static <T extends Comparable<T>> |
closedInf(T value)
Creates a new
Interval with a closed inferior
limit and an unbounded superior limit. |
static <T extends Comparable<T>> |
closedOpen(T inf,
T sup)
Creates a new
Interval with a closed inferior limit
and an open superior limit. |
static <T extends Comparable<T>> |
closedSup(T value)
Creates a new
Interval with a closed superior
limit and an unbounded inferior limit. |
boolean |
contains(T value)
Tells if this interval contains the given value.
|
static <T extends Comparable<T>> |
empty()
Returns the singleton instance of the "empty set"
Interval. |
boolean |
equals(Object other) |
T |
getInf()
Returns the value of the inferior limit
if it is defined.
|
T |
getSup()
Returns the value of the superior limit
if it is defined.
|
int |
hashCode() |
boolean |
includes(Interval<T> other)
Tells if this interval includes the given one.
|
Interval<T> |
intersect(Interval<T> other)
Returns an interval containing only those
elements that belongs to both this interval
and the given one.
|
boolean |
isClosed()
Tells if both the inferior limit and
the superior limit are closed.
|
boolean |
isClosedInf()
Tells if the inferior limit is closed.
|
boolean |
isClosedSup()
Tells if the superior limit is closed.
|
boolean |
isConsecutiveTo(Interval<T> other)
Tells if this interval is consecutive to the given one.
|
boolean |
isDisjointFrom(Interval<T> other)
Tells if this interval is disjoint frp, the given one.
|
boolean |
isEmpty()
Returns
true if this object is empty. |
boolean |
isEmptySet()
An interval is considered to be empty
if it is the empty set or if it is a
single point open interval in the form
(x,x). |
boolean |
isOpen()
Tells if both the inferior limit and
the superior limit are open.
|
boolean |
isOpenInf()
Tells if the inferior limit is open.
|
boolean |
isOpenSup()
Tells if the superior limit is open.
|
boolean |
isStrictlyConsecutiveTo(Interval<T> other)
This is a strict version of the
isConsecutiveTo(Interval)
method where a further check is made to ensure that the two
intervals are not overlapping. |
boolean |
isUnbounded()
Tells if both the inferior limit and
the superior limit are unbounded.
|
boolean |
isUnboundedInf()
Tells if the inferior limit is unbounded.
|
boolean |
isUnboundedSup()
Tells if the superior limit is unbounded.
|
static <T extends Comparable<T>> |
open(T inf,
T sup)
Creates a new open
Interval with the given limits. |
static <T extends Comparable<T>> |
openClosed(T inf,
T sup)
Creates a new
Interval with an open inferior limit
and a closed superior limit. |
static <T extends Comparable<T>> |
openInf(T value)
Creates a new
Interval with a open inferior
limit and an unbounded superior limit. |
static <T extends Comparable<T>> |
openSup(T value)
Creates a new
Interval with a open superior
limit and an unbounded inferior limit. |
boolean |
overlaps(Interval<T> other)
Tells if this interval overlaps the given one.
|
Interval<T> |
subtract(Interval<T> other)
Returns an interval containing only those
elements that belongs to this interval
but not to the given one.
|
String |
toString() |
static <T extends Comparable<T>> |
unbounded()
Returns the singleton instance of an unbounded
Interval. |
Interval<T> |
unify(Interval<T> other)
Returns an interval containing those elements
that belongs to at least one between this interval
and the given one.
|
protected Interval()
This constructor is intended to be used by reflection during de-serialization.
To create a new interval use factory methods.
protected Interval(org.nerd4j.utils.math.IntervalLimit<T> inf, org.nerd4j.utils.math.IntervalLimit<T> sup)
This constructor is intended to be used by extending classes only.
To create a new interval use the factory methods.
inf - the inferior limit of the interval.sup - the superior limit of the interval.public static <T extends Comparable<T>> Interval<T> empty()
Interval.
The empty set is considered to be an empty interval with undefined superior and inferior limits.
Invoking getInf() or getSup() on this instance will
throw a NoSuchElementException.
T - type of the elements in the interval.Interval.public static <T extends Comparable<T>> Interval<T> unbounded()
Interval.
Superior and inferior limits are not defined for an unbounded
interval so, invoking getInf() or getSup()
on this instance, will throw a NoSuchElementException.
T - type of the elements in the interval.Interval.public static <T extends Comparable<T>> Interval<T> closedInf(T value)
Interval with a closed inferior
limit and an unbounded superior limit.
Invoking getSup() on this instance
will throw a NoSuchElementException.
T - type of the elements in the interval.value - the inferior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> openInf(T value)
Interval with a open inferior
limit and an unbounded superior limit.
Invoking getSup() on this instance
will throw a NoSuchElementException.
T - type of the elements in the interval.value - the inferior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> closedSup(T value)
Interval with a closed superior
limit and an unbounded inferior limit.
Invoking getInf() on this instance
will throw a NoSuchElementException.
T - type of the elements in the interval.value - the superior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> openSup(T value)
Interval with a open superior
limit and an unbounded inferior limit.
Invoking getInf() on this instance
will throw a NoSuchElementException.
T - type of the elements in the interval.value - the superior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> closed(T inf, T sup)
Interval with the given limits.T - type of the elements in the interval.inf - the inferior limit.sup - the superior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> open(T inf, T sup)
Interval with the given limits.T - type of the elements in the interval.inf - the inferior limit.sup - the superior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> closedOpen(T inf, T sup)
Interval with a closed inferior limit
and an open superior limit.T - type of the elements in the interval.inf - the inferior limit.sup - the superior limit.Interval.RequirementFailure - if limits are inconsistent.public static <T extends Comparable<T>> Interval<T> openClosed(T inf, T sup)
Interval with an open inferior limit
and a closed superior limit.T - type of the elements in the interval.inf - the inferior limit.sup - the superior limit.Interval.RequirementFailure - if limits are inconsistent.public boolean isEmpty()
true if this object is empty.public boolean isEmptySet()
(x,x).
The method isEmpty() returns
true in both cases. This method
returns true only if this interval
is the empty set.
true if this interval is the empty set.public boolean isUnbounded()
true if both limit are unbounded.public boolean isUnboundedInf()
true if the inferior limit is unbounded.public boolean isUnboundedSup()
true if the superior limit is unbounded.public boolean isClosed()
true if both limit are closed.public boolean isClosedInf()
true if the inferior limit is closed.public boolean isClosedSup()
true if the superior limit is closed.public boolean isOpen()
true if both limit are open.public boolean isOpenInf()
true if the inferior limit is open.public boolean isOpenSup()
true if the superior limit is open.public T getInf()
NoSuchElementException
will be thrown.NoSuchElementException - if the inferior
limit is unbounded or this is the empty set.public T getSup()
NoSuchElementException
will be thrown.NoSuchElementException - if the superior
limit is unbounded or this is the empty set.public boolean contains(T value)
value - the value to check.true it the value belongs to the interval.RequirementFailure - if the provided value is null.public boolean includes(Interval<T> other)
An interval A is included into another interval B if any element of A belongs also to B.
The empty set is included into any other interval.
other - the interval to check.true if the other interval is included in this one.RequirementFailure - if the other interval is null.public boolean overlaps(Interval<T> other)
Two intervals overlap if they have at least one
element in common and if they are not including
each other. In mathematical notation: two intervals
A and B overlap if A ∩ B ≠ ∅
and A ⊈ B and B ⊈ A.
Since there must exist at least one element in common
an empty interval cannot overlap with any other interval.
other - the interval to check.true if this interval overlaps the other one.RequirementFailure - if the other interval is null.public boolean isDisjointFrom(Interval<T> other)
Two intervals are said to be disjoint if they have
no elements in common. In mathematical notation:
two intervals A and B are disjoint
if A ∩ B = ∅.
Since two intervals are disjoint if they have no elements in common then any empty interval is disjoint from any other interval including itself.
other - the interval to check.true if this interval overlaps the other one.RequirementFailure - if the other interval is null.public boolean isConsecutiveTo(Interval<T> other)
Two intervals are considered to be consecutive if they
share one limit and at least for one of the intervals
the given limit is closed. (x,y),[y,z], [x,y],(y,z]
and (x,y],[y,z) are all consecutive intervals
while [x,y),(y,z] are not consecutive.
The empty set is consecutive to any other interval.
other - the interval to check.RequirementFailure - if the other interval is null.public boolean isStrictlyConsecutiveTo(Interval<T> other)
isConsecutiveTo(Interval)
method where a further check is made to ensure that the two
intervals are not overlapping.
In this case (x,y),[y,z] and [x,y],(y,z]
are still considered to be consecutive while
(x,y],[y,z) are not.
The empty set is strictly consecutive to any other interval.
other - the interval to check.RequirementFailure - if the other interval is null.public boolean canUnify(Interval<T> other)
When we work with sets, the operation of union is always possible. If we unify two sets, the result is still a set. When we work with intervals this is not true.
By definition, a totally ordered set I is an interval
if: for each x such that inf(I) <= x <= sup(I)
we have that x belongs to I.
If we unify [0,5] and [15,20] the result is
not an interval because, for example the value 10, does
not belong to [0,5]∪[15,20]
Two intervals can be unified if:
A special case is given by the empty intervals. While the empty
set can be unified to any other interval, an empty interval can
be unified with another interval only if its limits lay within
the limits of the other interval. For example [0,10] and
(5,5) can be unified while [5,10] and (0,0)
cannot.
If this method returns true the method unify(Interval)
will return a new Interval that represents the union of this
interval with the given one. Otherwise, if this method returns false
the method unify(Interval) will throw a NoSuchIntervalException.
other - the interval to check.true if this interval can be unified with the other one.RequirementFailure - if the other interval is null.public boolean canSubtract(Interval<T> other)
When we work with sets, the operation of subtraction is always possible. If we subtract two sets, the result is still a set. When we work with intervals this is not true.
By definition, a totally ordered set I is an interval
if: for each x such that inf(I) <= x <= sup(I)
we have that x belongs to I.
If we subtract (5,15) from [0,20] the result is
not an interval because, for example the value 10, does
not belong to [0,5]∪[15,20]
We can subtract an interval A from another interval B only of
B is not entirely included into A. For example, from the interval
[0,20], we can subtract @code [10,20]} but cannot subtract
[10,15] or [10,20).
A special case is given by the empty intervals. Se can always
subtract an empty interval even if it is entirely included
into the other one. For example, from the interval [0,20],
we can subtract [10,10), (10,10] and (10,10).
If this method returns true the method subtract(Interval)
will return a new Interval that represents this interval minus
the given one. Otherwise, if this method returns false
the method subtract(Interval) will throw a NoSuchIntervalException.
other - the interval to check.true if this interval can subtract the other one.RequirementFailure - if the other interval is null.public Interval<T> intersect(Interval<T> other)
If one of the intervals is the empty set or if the two intervals are disjoint then the empty set will be returned.
other - the interval to intersect.RequirementFailure - if the other interval is null.public Interval<T> unify(Interval<T> other)
If one of the intervals is the empty the other one will be returned.
Two intervals can be unified if either they overlap
or they are consecutive. If none of this condition
holds then a NoSuchIntervalException will
be thrown.
If the methog canUnify(Interval) returns false
this method will throw a NoSuchIntervalException.
other - the interval to intersect.RequirementFailure - if the other interval is null.NoSuchIntervalException - it the two intervals cannot be unified.public Interval<T> subtract(Interval<T> other)
If one of the intervals is the empty set or if the two intervals are disjoint this interval will be returned.
other - the interval to subtract.RequirementFailure - if the other interval is null.Copyright © 2011–2020 Nerd4j. All rights reserved.