net.time4j.engine

Interface TimeSpan<U>

Type Parameters:

U - generic type of time unit

All Known Implementing Classes:

AbstractDuration, Duration

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 and 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 and 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 Detail

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)