Package net.time4j.engine

Interface TimeSpan<U>

Type Parameters:
U - generic type of time unit
All Known Implementing Classes:
AbstractDuration, Duration, MachineTime, Months, Quarters, SingleUnitTimeSpan, Weeks, Years
public interface TimeSpan<U>

Represents a common time span with an associated sign and a sequence of time units and related amounts.

Author:
Meno Hochschild

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    TimeSpan.Item<U>
    Represents a single item of a time span which is based on only one time unit and has a non-negative amount.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T extends TimePoint<? super U,​ T>>
    T
    addTo​(T time)
    Adds this time span to given time point.
    boolean
    contains​(U unit)
    Queries if given time unit is part of this time span.
    long
    getPartialAmount​(U unit)
    Yields the partial amount associated with given time unit.
    List<TimeSpan.Item<U>>
    getTotalLength()
    Yields all containted time span items with amount and unit in the order from largest to smallest time units.
    boolean
    isEmpty()
    Queries if this time span is empty.
    boolean
    isNegative()
    Queries if this time span is negative.
    boolean
    isPositive()
    Queries if this time span is positive.
    <T extends TimePoint<? super U,​ T>>
    T
    subtractFrom​(T time)
    Subtracts this time span from given time point.

  • Method Details

    • getTotalLength

      List<TimeSpan.Item<U>> getTotalLength()

      Yields all containted time span items with amount and unit in the order from largest to smallest time units.

      Returns:
      unmodifiable list sorted by precision of units in ascending order where every time unit exists at most once

    • contains

      boolean contains​(U unit)

      Queries if given time unit is part of this time span.

      By default the implementation uses following expression: 

        for (Item<?> item : getTotalLength()) {
      if (item.getUnit().equals(unit)) {
          return (item.getAmount() > 0);
      }
  }
  return false;
      Parameters:
      unit - time unit to be asked (optional)
      Returns:
      true if exists else false
      See Also:
      getPartialAmount(U)

    • getPartialAmount

      long getPartialAmount​(U unit)

      Yields the partial amount associated with given time unit.

      The method returns 0 if this time span does not contain given time unit. In order to get the total length/amount of this time span users have to evaluate the method getTotalLength() instead.

      Parameters:
      unit - time unit (optional)
      Returns:
      amount as part of time span (>= 0)

    • isNegative

      boolean isNegative()

      Queries if this time span is negative.

      A negative time span relates to the subtraction of two time points where first one is after second one. The partial amounts of every time span are never negative. Hence this attribute is not associated with the partial amounts but only with the time span itself.

      Note: An empty time span itself is never negative in agreement with the mathematical relation (-1) * 0 = 0.

      Returns:
      true if negative and not empty else false

    • isPositive

      boolean isPositive()

      Queries if this time span is positive.

      A time span is positive if it is neither empty nor negative.

      Returns:
      true if positive and not empty else false
      See Also:
      isEmpty(), isNegative()

    • isEmpty

      boolean isEmpty()

      Queries if this time span is empty.

      Per definition an empty time span has no items with a partial amount different from 0.

      Returns:
      true if empty else false

    • addTo

      <T extends TimePoint<? super U,​ T>> T addTo​(T time)

      Adds this time span to given time point.

      Is equivalent to the expression time.plus(this). Due to better readability usage of the TimePoint-method is recommended. Implementations are required to document the used algorithm in detailed manner.

      Type Parameters:
      T - generic type of time point
      Parameters:
      time - reference time point to add this time span to
      Returns:
      new time point as result of addition
      See Also:
      subtractFrom(TimePoint)

    • subtractFrom

      <T extends TimePoint<? super U,​ T>> T subtractFrom​(T time)

      Subtracts this time span from given time point.

      Is equivalent to the expression time.minus(this). Due to better readability usage of the TimePoint-method is recommended. Implementations are required to document the used algorithm in detailed manner.

      Type Parameters:
      T - generic type of time point
      Parameters:
      time - reference time point to subtract this time span from
      Returns:
      new time point as result of subtraction
      See Also:
      addTo(TimePoint)