Package net.time4j.engine

Class TimePoint<U,​T extends TimePoint<U,​T>>

java.lang.Object
net.time4j.engine.ChronoEntity<T>
net.time4j.engine.TimePoint<U,​T>
Type Parameters:
U - generic type of time units compatible to ChronoUnit
T - generic type of self reference
All Implemented Interfaces:
Serializable, Comparable<T>, ChronoDisplay
Direct Known Subclasses:
Calendrical, EthiopianTime, HebrewTime, Moment, PlainTime, PlainTimestamp
public abstract class TimePoint<U,​T extends TimePoint<U,​T>> extends ChronoEntity<T> implements Comparable<T>, Serializable

Represents an immutable time point along a time axis which is directed into the future.

Display and change chronological element values

The time point consists of chronological elements. This base class delegates the time arithmetic to the associated time axis respective to the underlying rules of elements and units. However, any concrete subclass is required to define the state and reflect it in all get()-methods and also to specify the serialization behaviour.

Element values can only be changed by creating a new immutable copy of the original instance. This is done via all with()-methods.

Time axis

If the referenced time axis is the UTC-timeline (that is a time point is defined relative to the start of UTC epoch - see package summary) then any implementation must also implement the interface UniversalTime. In every other case we have a local time axis. All time units are to be defined referencing the time axis. For example, second units are interpreted as local UT1-seconds on a local timestamp but on a UniversalTime before 1972 as global UT1-seconds and after 1972 as atomic SI-seconds. Hence Time4J has even defined different second units in the main package. Applications should therefore take much care if they transform a duration from one time axis to another one.

Sorting

Unless explicitly stated otherwise sorting of time points is always in strict temporal order and consistent with equals(). In case of doubt the documentation of the subclass is leading. Alternatively, subclasses are free to implement the interface Temporal to enable a temporal order. A pure temporal state of any implementation is strongly recommended.

Addition (or subtraction) of a time span to a time point

These operations are performed by all plus()- and minus()- methods. A time span can either be a single time unit, or it consists of several time units.

If given time unit does not have a fixed length (for example months) then the result of an addition can deviate from the expected element value to be considered. In case of multiple additions care is required. In case of doubt the original value should be saved for a later addition. Example with additions of months in one or two steps (pseudo-code):

  • [2011-08-31] + [P1M] = [2011-09-30]
  • [2011-09-30] + [P1M] = [2011-10-30]
  • [2011-08-31] + [P2M] = [2011-10-31]

Difference of time points

The difference of time points results in a time span. The result can either be expressed in one time unit only, or in multiple units which represent the base unit of associated chronological element. In latter case users have to define a metric, too.

Implementation notes

  • All subclasses must be final und immutable.
  • Documentation of supported and registered elements is required.
  • For a suitable choice of the type U of time units it should be noted that the time units must correspond to the internal state of a time point because otherwise the calculation of a time span between two time points cannot be complete. For example it would be a mistake to allow milliseconds only for a time point which even has nanoseconds.
  • The natural order should be consistent with equals().
Author:
Meno Hochschild
See Also:
Chronology, TimeAxis, Temporal

  • Constructor Summary

    Constructors
    Constructor
    Description
    TimePoint()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract int
    compareTo​(T timePoint)
    Compares two time points preferably by their temporal positions on the common time axis.
    abstract boolean
    equals​(Object obj)
    Compares the whole state of this instance with given object.
    abstract int
    hashCode()
    Subclasses must redefine this method corresponding to the behaviour of equals().
    static <U,​ T extends TimePoint<U,​ T>>
    T
    max​(T t1, T t2)
    Determines the maximum of both time points.
    static <U,​ T extends TimePoint<U,​ T>>
    T
    min​(T t1, T t2)
    Determines the minimum of both time points.
    T
    minus​(long amount, U unit)
    Subtracts given amount in units from this time point and yields the result of subtraction.
    T
    minus​(TimeSpan<? extends U> timeSpan)
    Subtracts given time span from this time point and yields the result of subtraction.
    T
    plus​(long amount, U unit)
    Adds given amount in units to this time point and yields the result of addition.
    T
    plus​(TimeSpan<? extends U> timeSpan)
    Adds the given time span to this time point and yields the result of the addition.
    abstract String
    toString()
    Provides a complete textual representation of the state of this time point.
    <P> P
    until​(T end, TimeMetric<? extends U,​P> metric)
    Calculates the (most normalized) time span between this time point and given end time point using the given metric.
    long
    until​(T end, U unit)
    Calculates the temporal distance between this time point and given end time point in only one time unit.

    Methods inherited from class net.time4j.engine.ChronoEntity

    contains, get, get, getInt, getMaximum, getMinimum, getRegisteredElements, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • TimePoint

      public TimePoint()

  • Method Details

    • compareTo

      public abstract int compareTo​(T timePoint)

      Compares two time points preferably by their temporal positions on the common time axis.

      Implementation note: In order to make the natural order consistent with equals() the whole state must be taken into account, with preference for those attributes which define the temporal position on the time axis.

      Specified by:
      compareTo in interface Comparable<U>
      See Also:
      equals(Object)

    • plus

      public T plus​(TimeSpan<? extends U> timeSpan)

      Adds the given time span to this time point and yields the result of the addition.

      Delegates to TimeSpan.addTo(TimePoint).

      Parameters:
      timeSpan - time span to be added to this instance
      Returns:
      result of addition as changed copy, this instance remains unaffected
      Throws:
      RuleNotFoundException - if any time unit is not registered and does also not implement BasicUnit to yield a suitable unit rule for the underlying time axis
      ArithmeticException - in case of numerical overflow
      See Also:
      minus(TimeSpan)

    • minus

      public T minus​(TimeSpan<? extends U> timeSpan)

      Subtracts given time span from this time point and yields the result of subtraction.

      Delegiert an TimeSpan.subtractFrom(TimePoint).

      Parameters:
      timeSpan - time span to be subtracted from this instance
      Returns:
      result of subtraction as changed copy, this instance remains unaffected
      Throws:
      RuleNotFoundException - if any time unit is not registered and does also not implement BasicUnit to yield a suitable unit rule for the underlying time axis
      ArithmeticException - in case of numerical overflow
      See Also:
      plus(TimeSpan)

    • plus

      public T plus​(long amount, U unit)

      Adds given amount in units to this time point and yields the result of addition.

      Similar to plus(TimeSpan) but with the difference that the timespan is only given in one single time unit. Example in pseudo-code:

      • [2011-05-31].plus(1, <MONTHS>) = [2011-06-30]
      • [2011-05-31].plus(4, <DAYS>) = [2011-06-04]
      • [2011-06-04].plus(-4, <DAYS>) = [2011-05-31]
      • [2010-04-29].plus(397, <DAYS>) = [2011-05-31]
      • [2010-04-29].plus(13, <MONTHS>) = [2011-05-29]
      • [2010-04-29].plus(-2, <MONTHS>) = [2010-02-28]
      • [2010-04-29].plus(1, <YEARS>) = [2011-04-29]
      Parameters:
      amount - amount to be added (maybe negative)
      unit - time unit
      Returns:
      result of addition as changed copy, this instance remains unaffected
      Throws:
      RuleNotFoundException - if given time unit is not registered and does also not implement BasicUnit to yield a suitable unit rule for the underlying time axis
      ArithmeticException - in case of numerical overflow
      See Also:
      plus(TimeSpan)

    • minus

      public T minus​(long amount, U unit)

      Subtracts given amount in units from this time point and yields the result of subtraction.

      Parameters:
      amount - amount to be subtracted (maybe negative)
      unit - time unit
      Returns:
      result of subtraction as changed copy, this instance remains unaffected
      Throws:
      RuleNotFoundException - if given time unit is not registered and does also not implement BasicUnit to yield a suitable unit rule for the underlying time axis
      ArithmeticException - in case of numerical overflow
      See Also:
      plus(long, U)

    • until

      public <P> P until​(T end, TimeMetric<? extends U,​P> metric)

      Calculates the (most normalized) time span between this time point and given end time point using the given metric.

      Type Parameters:
      P - generic type of time span result
      Parameters:
      end - end time point
      metric - temporal distance metric
      Returns:
      difference between this and given end time point expressed as time span
      Throws:
      ArithmeticException - in case of numerical overflow

    • until

      public long until​(T end, U unit)

      Calculates the temporal distance between this time point and given end time point in only one time unit.

      Similar to until(TimePoint, TimeMetric) but with the difference that the time span is onyl calculated in one time unit as long-primitive. In many cases a remainder of subtraction will be left if given unit is not the smallest possible unit. Time points whose element values differ less than one base unit will be considered as equal. Examples in pseudo-code:

      • [2011-05-31].until([2011-06-04], <MONTHS>) = 0
      • [2011-05-31].until([2011-06-04], <DAYS>) = 4
      • [2011-06-04].until([2011-05-31], <DAYS>) = -4
      • [2010-04-29].until([2011-05-31], <DAYS>) = 397
      • [2010-04-29].until([2011-05-31], <MONTHS>) = 13
      • [2010-04-29].until([2011-05-31], <YEARS>) = 1
      • [2010-05-31].until([2011-05-31], <YEARS>) = 1
      • [2010-06-01].until([2011-05-31], <YEARS>) = 0
      Parameters:
      end - end time point
      unit - time unit
      Returns:
      difference between this and given end time point as count of given time unit
      Throws:
      RuleNotFoundException - if given time unit is not registered and does also not implement BasicUnit to yield a suitable unit rule for the underlying time axis
      ArithmeticException - in case of numerical overflow
      See Also:
      until(TimePoint, TimeMetric)

    • min

      public static <U,​ T extends TimePoint<U,​ T>> T min​(T t1, T t2)

      Determines the minimum of both time points.

      Type Parameters:
      U - generic type of time units compatible to ChronoUnit
      T - generic type of self reference
      Parameters:
      t1 - first time point
      t2 - second time point
      Returns:
      minimum of t1 and t2

    • max

      public static <U,​ T extends TimePoint<U,​ T>> T max​(T t1, T t2)

      Determines the maximum of both time points.

      Type Parameters:
      U - generic type of time units compatible to ChronoUnit
      T - generic type of self reference
      Parameters:
      t1 - first time point
      t2 - second time point
      Returns:
      maximum of t1 and t2

    • equals

      public abstract boolean equals​(Object obj)

      Compares the whole state of this instance with given object.

      Implementations will usually define their state only based on the temporal position on the time axis because this is the most intuitive approach. Exceptions from this rule should be explicitly documented and reasoned.

      Overrides:
      equals in class Object
      See Also:
      compareTo(TimePoint)

    • hashCode

      public abstract int hashCode()

      Subclasses must redefine this method corresponding to the behaviour of equals().

      Overrides:
      hashCode in class Object

    • toString

      public abstract String toString()

      Provides a complete textual representation of the state of this time point.

      The textual description often follows the conventions of ISO-8601. Usually the description starts with the chronological informations which are coarse-grained and ends with those ones which are fine-grained (for example the ISO-notation YYYY-MM-DD).

      Overrides:
      toString in class Object