net.sf.jtemporal
Class Period

java.lang.Object
  net.sf.jtemporal.Period

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Period>

public class Period
extends java.lang.Object
implements java.lang.Comparable<Period>, java.io.Serializable

Represents a "half-open" immutable time range (which includes the start instant, but not the end instant).
It does not implement Cloneable, because there is no reason to clone an immutable object.

Note: if the period is [negativeInfinity, positiveInfinity[ , then all the instants are contained, including positive infinity.

Version:

$Id: Period.java,v 1.9 2007/09/14 20:03:10 tabeck Exp $

See Also:

Serialized Form

Constructor Summary

Period(Instant start, Instant end)
Constructs an immutable Instant instance.

Method Summary

int	compareTo(Period p) Orders first by start and if start instants are equals, by end.
boolean	contains(Instant i) Returns true if this period contains the instant i.
boolean	contains(Period p) Returns true if this period contains of is equal to p.
boolean	equals(java.lang.Object o) Compares this object against the specified object.
Period	except(Period p) Returns the part of this period which is not part of p.
Instant	getEnd() The instant delimiting the end of this period.
Instant	getStart() The instant delimiting the beginning of this period.
int	hashCode() Computes a hash code for this Period.
Period	intersect(Period p) Returns a period representing the common part in the two periods.
boolean	meets(Period p) Returns true if this period meets p.
boolean	meetsAfter(Period p) Returns true if this period meets and succeeds p.
boolean	meetsBefore(Period p) Returns true if this period meets and precedes p.
boolean	overlaps(Period p) Returns true if there exists an intersection between the two periods.
boolean	precedes(Instant i) Return true is this period precedes i.
boolean	precedes(Period p) Return true is this period precedes p.
Period	precedingPeriod(Period p) Returns the part of this period that precedes p, or null if p.start < this.start
Period	succedingPeriod(Period p) Returns the part of this period that succeeds p, or null if p.end > this.end
boolean	succeeds(Instant i) Returns true if this period succeeds i.
boolean	succeeds(Period p) Returns true if this period succeeds p.
java.lang.String	toString() Textual representation of this object.
Period	union(Period p) Returns the result of the merge of two periods.

Methods inherited from class java.lang.Object

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

Constructor Detail

Period

public Period(Instant start,
              Instant end)

Constructs an immutable Instant instance.

Throws:

java.lang.IllegalArgumentException - when start >= end

Method Detail

compareTo

public int compareTo(Period p)

Orders first by start and if start instants are equals, by end.
No matter the periods are overlapping or not.

Specified by:

compareTo in interface java.lang.Comparable<Period>

Returns:

0 only when equals is true

equals

public boolean equals(java.lang.Object o)

Compares this object against the specified object. The result is true if and only if the argument is not null and is a Period object that contains the same start and end values as this object.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with.

Returns:

true if the objects are the same; false otherwise.

hashCode

public int hashCode()

Computes a hash code for this Period.
The result is the binary exclusive OR of the hash codes of start and end.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

getStart

public Instant getStart()

The instant delimiting the beginning of this period.
The start instant is part of the period.

Returns:

the start instant

getEnd

public Instant getEnd()

The instant delimiting the end of this period.
The end instant is not part of the period.

Returns:

the end instant.

precedes

public boolean precedes(Period p)

Return true is this period precedes p.
Note: returns false if the periods are overlapping.

Parameters:

p - the period checked to be succeeding.

Returns:

this.end <= p.start

precedes

public boolean precedes(Instant i)

Return true is this period precedes i.
Note: returns false if the period contains i.

Parameters:

i - the instant checked to be succeeding.

Returns:

this.end <= i

succeeds

public boolean succeeds(Period p)

Returns true if this period succeeds p.
Note: returns false if the periods are overlapping.

Parameters:

p - the period checked to be preceding.

Returns:

this.start >= p.end

succeeds

public boolean succeeds(Instant i)

Returns true if this period succeeds i.
Note: returns false if the period contains i.

Parameters:

p - the period checked to be preceding.

Returns:

this.start > i

meets

public boolean meets(Period p)

Returns true if this period meets p.

Parameters:

p - the period checked to be immediately succeeding or preceding.

Returns:

this.end = p.start OR this.start = p.end

meetsBefore

public boolean meetsBefore(Period p)

Returns true if this period meets and precedes p.

Parameters:

p - the period checked to be immediately succeeding.

Returns:

this.end = p.start

meetsAfter

public boolean meetsAfter(Period p)

Returns true if this period meets and succeeds p.

Parameters:

p - the period checked to be immediately succeeding.

Returns:

this.start = p.end

contains

public boolean contains(Period p)

Returns true if this period contains of is equal to p.

Parameters:

p - the period checked to be contained.

Returns:

this.start.compareTo(p.start) <= 0 && this.end.compareTo(p.end) >= 0

contains

public boolean contains(Instant i)

Returns true if this period contains the instant i.
Note: if this.start is negative infinity and this.end is positiveInfinity, then all the instants are contained, including positive infinity.

Parameters:

i - the instant checked to be contained.

Returns:

this.start.compareTo(i) <= 0 && this.end.compareTo(i) > 0

overlaps

public boolean overlaps(Period p)

Returns true if there exists an intersection between the two periods.

Parameters:

p - the period to be checked for intersection against this period

Returns:

true when this.start < p.end and this.end > p.start

union

public Period union(Period p)

Returns the result of the merge of two periods.
One period must meet the other.

Parameters:

p - the period to be merged to this period

Returns:

a new period representing the merge

Throws:

java.lang.IllegalArgumentException - when the periods does not match

except

public Period except(Period p)

Returns the part of this period which is not part of p. but if p.contains(this) or p.equals(this) it returns null

Parameters:

p - the period to be subtracted from this period

Returns:

the part of this period which is not part of p.

Throws:

java.lang.IllegalArgumentException - when operation should return two distinct periods

precedingPeriod

public Period precedingPeriod(Period p)

Returns the part of this period that precedes p, or null if p.start < this.start

Parameters:

p - the period that meetsAfter the result

Returns:

the part of this period that precedes p, or null.

succedingPeriod

public Period succedingPeriod(Period p)

Returns the part of this period that succeeds p, or null if p.end > this.end

Parameters:

p - the period that meetsBefore the result

Returns:

the part of this period that succeeds p, or null.

intersect

public Period intersect(Period p)

Returns a period representing the common part in the two periods.
Note: returns null if this.overlaps(p) == false

Parameters:

p - the period to be intersected with this period

Returns:

the intersection between this period and p

toString

public java.lang.String toString()

Textual representation of this object.

Overrides:

toString in class java.lang.Object

Returns:

"Period:(" + start + "," + end + ")"