Package net.time4j.range

Class SingleUnitTimeSpan<U extends IsoDateUnit,D extends SingleUnitTimeSpan<U,D>>

java.lang.Object

net.time4j.range.SingleUnitTimeSpan<U,D>

Type Parameters:

U - generic type of calendrical units

All Implemented Interfaces:

Serializable, Comparable<D>, TimeSpan<U>

Direct Known Subclasses:

Months, Quarters, Weeks, Years

public abstract class SingleUnitTimeSpan<U extends IsoDateUnit,D extends SingleUnitTimeSpan<U,D>>
extends Object
implements TimeSpan<U>, Comparable<D>, Serializable

Represents a time span in one calendrical unit only.

Since:

3.21/4.17

Author:

Meno Hochschild

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface net.time4j.engine.TimeSpan

TimeSpan.Item<U>

Method Summary

Modifier and Type	Method	Description
D	abs()	Yields a copy with the absolute amount.
<T extends TimePoint<? super U, T>> T	addTo(T time)	Adds this time span to given time point.
int	compareTo(D other)
boolean	contains(IsoDateUnit unit)	Queries if given time unit is part of this time span.
boolean	equals(Object obj)
int	getAmount()	Yields the count of units as integer-based amount.
long	getPartialAmount(IsoDateUnit 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.
U	getUnit()	Yields the associated unit.
int	hashCode()
D	inverse()	Yields a copy with the negated amount.
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.
D	minus(int amount)	Yields a copy with the subtracted amount.
D	minus(D duration)	Yields a copy with the subtracted duration.
D	multipliedBy(int factor)	Yields a copy with the multiplied amount.
D	plus(int amount)	Yields a copy with the added amount.
D	plus(D duration)	Yields a copy with the added duration.
<T extends TimePoint<? super U, T>> T	subtractFrom(T time)	Subtracts this time span from given time point.
Duration<U>	toStdDuration()	Converts this instance to a general duration with the same amount and unit.
String	toString()	Prints in ISO-8601-format "PnU" (n=amount, U=unit).
String	toString(Locale locale, TextWidth width)	Prints this duration in a localized way with given text width.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Details

getAmount

public int getAmount()

Yields the count of units as integer-based amount.

Returns:

int

getUnit

public U getUnit()

Yields the associated unit.

Returns:

calendrical unit

compareTo

public int compareTo(D other)

Specified by:

compareTo in interface Comparable<U extends IsoDateUnit>

getTotalLength

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

Description copied from interface: TimeSpan

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

Specified by:

getTotalLength in interface TimeSpan<U extends IsoDateUnit>

Returns:

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

contains

public boolean contains(IsoDateUnit unit)

Description copied from interface: TimeSpan

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;
 

Specified by:

contains in interface TimeSpan<U extends IsoDateUnit>

Parameters:

unit - time unit to be asked (optional)

Returns:

true if exists else false

See Also:

getPartialAmount(U)

getPartialAmount

public long getPartialAmount(IsoDateUnit unit)

Description copied from interface: TimeSpan

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 TimeSpan.getTotalLength() instead.

Specified by:

getPartialAmount in interface TimeSpan<U extends IsoDateUnit>

Parameters:

unit - time unit (optional)

Returns:

amount as part of time span (>= 0)

isNegative

public boolean isNegative()

Description copied from interface: TimeSpan

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.

Specified by:

isNegative in interface TimeSpan<U extends IsoDateUnit>

Returns:

true if negative and not empty else false

isPositive

public boolean isPositive()

Description copied from interface: TimeSpan

Queries if this time span is positive.

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

Specified by:

isPositive in interface TimeSpan<U extends IsoDateUnit>

Returns:

true if positive and not empty else false

See Also:

TimeSpan.isEmpty(), TimeSpan.isNegative()

isEmpty

public boolean isEmpty()

Description copied from interface: TimeSpan

Queries if this time span is empty.

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

Specified by:

isEmpty in interface TimeSpan<U extends IsoDateUnit>

Returns:

true if empty else false

addTo

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

Description copied from interface: TimeSpan

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.

Specified by:

addTo in interface TimeSpan<U extends IsoDateUnit>

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:

TimeSpan.subtractFrom(TimePoint)

subtractFrom

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

Description copied from interface: TimeSpan

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.

Specified by:

subtractFrom in interface TimeSpan<U extends IsoDateUnit>

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:

TimeSpan.addTo(TimePoint)

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Prints in ISO-8601-format "PnU" (n=amount, U=unit).

Negative durations will get a preceding sign before "P". Note that gregorian and week-based years have the same representation using the symbol Y.

Overrides:

toString in class Object

Returns:

the duration in ISO-8601-format

toString

public String toString(Locale locale,
 TextWidth width)

Prints this duration in a localized way with given text width.

Parameters:

locale - the locale to be applied

width - the text width to be applied

Returns:

formatted localized representation of this duration

Since:

5.0

abs

public D abs()

Yields a copy with the absolute amount.

Returns:

immutable copy with the absolute amount

Throws:

ArithmeticException - if numeric overflow occurs (only in case of Integer.MIN_VALUE)

inverse

public D inverse()

Yields a copy with the negated amount.

Returns:

immutable copy with the reverse sign

Throws:

ArithmeticException - if numeric overflow occurs (only in case of Integer.MIN_VALUE)

plus

public D plus(int amount)

Yields a copy with the added amount.

Parameters:

amount - the amount to be added

Returns:

result of addition as immutable copy

Throws:

ArithmeticException - if numeric overflow occurs

plus

public D plus(D duration)

Yields a copy with the added duration.

Parameters:

duration - the duration to be added

Returns:

result of addition as immutable copy

Throws:

ArithmeticException - if numeric overflow occurs

minus

public D minus(int amount)

Yields a copy with the subtracted amount.

Parameters:

amount - the amount to be subtracted

Returns:

result of subtraction as immutable copy

Throws:

ArithmeticException - if numeric overflow occurs

minus

public D minus(D duration)

Yields a copy with the subtracted duration.

Parameters:

duration - the duration to be added

Returns:

result of subtraction as immutable copy

Throws:

ArithmeticException - if numeric overflow occurs

multipliedBy

public D multipliedBy(int factor)

Yields a copy with the multiplied amount.

Parameters:

factor - multiplication factor to be applied

Returns:

immutable copy with the multiplied amount

Throws:

ArithmeticException - if numeric overflow occurs

toStdDuration

public Duration<U> toStdDuration()

Converts this instance to a general duration with the same amount and unit.

Returns:

Duration