Package net.time4j

Class MachineTime<U>

java.lang.Object

net.time4j.MachineTime<U>

Type Parameters:

U - either TimeUnit or SI

All Implemented Interfaces:

Serializable, Comparable<MachineTime<U>>, TimeSpan<U>

public final class MachineTime<U>
extends Object
implements TimeSpan<U>, Comparable<MachineTime<U>>, Serializable

Represents a duration for machine times in decimal seconds with nanosecond precision.

Note: Other time units are NOT contained but can be used in construction of a machine time. Example:

  MachineTime<TimeUnit> mt = MachineTime.of(1, TimeUnit.HOURS);
  System.out.println(mt.contains(TimeUnit.HOURS)); // false
  System.out.println(mt.getSeconds); // 3600L
 

Since:

5.0

Author:

Meno Hochschild

See Also:

TimeUnit.SECONDS, TimeUnit.NANOSECONDS, SI.SECONDS, SI.NANOSECONDS, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MachineTime.Formatter	Non-localized and user-defined format for machine-time-durations based on a pattern containing some standard symbols and literals.

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

TimeSpan.Item<U>

Field Summary

Fields

Modifier and Type	Field	Description
static TimeMetric<TimeUnit,MachineTime<TimeUnit>>	ON_POSIX_SCALE	Reversible metric on the POSIX scale (without leap seconds).
static TimeMetric<TimeUnit,MachineTime<SI>>	ON_UTC_SCALE	Reversible metric on the UTC scale (inclusive leap seconds).

Method Summary

Modifier and Type	Method	Description
MachineTime<U>	abs()	Converts this machine duration to its absolute amount.
<T extends TimePoint<? super U, T>> T	addTo(T time)	Adds this time span to given time point.
int	compareTo(MachineTime<U> other)	Method of the Comparable-interface.
boolean	contains(Object unit)	Queries if given time unit is part of this time span.
MachineTime<U>	dividedBy(long divisor, RoundingMode roundingMode)	Divides this duration by given divisor using given rounding mode.
boolean	equals(Object obj)
static MachineTime<TimeUnit>	from(Duration threeten)	Converts given JSR-310-duration to a machine time.
int	getFraction()	Yields the normalized nanosecond fraction of this duration.
long	getPartialAmount(Object unit)	Yields the partial amount associated with given time unit.
TimeScale	getScale()	Yields the related time scale.
long	getSeconds()	Yields the normalized seconds of this duration.
List<TimeSpan.Item<U>>	getTotalLength()	Yields all containted time span items with amount and unit in the order from largest to smallest time units.
int	hashCode()
MachineTime<U>	inverse()	Creates a copy with inversed sign.
boolean	isEmpty()	Queries if this time span is empty.
boolean	isLongerThan(MachineTime<U> other)	Compares the absolute lengths and is equivalent to abs().compareTo(other.abs()) > 0.
boolean	isNegative()	Queries if this time span is negative.
boolean	isPositive()	Queries if this time span is positive.
boolean	isShorterThan(MachineTime<U> other)	Compares the absolute lengths and is equivalent to abs().compareTo(other.abs()) < 0.
MachineTime<U>	minus(long amount, U unit)	Subtracts given temporal amount from this machine time.
MachineTime<U>	minus(MachineTime<U> duration)	Subtracts given temporal amount from this machine time.
MachineTime<U>	multipliedBy(double factor)	Multiplies this duration with given decimal factor.
MachineTime<U>	multipliedBy(long factor)	Multiplies this duration with given factor.
static MachineTime<TimeUnit>	of(long amount, TimeUnit unit)	Creates a machine time duration on the POSIX scale.
static MachineTime<SI>	of(long amount, SI unit)	Creates a machine time duration on the UTC scale.
static MachineTime<TimeUnit>	ofPosixSeconds(double seconds)	Creates a machine time duration on the POSIX scale.
static MachineTime<TimeUnit>	ofPosixSeconds(BigDecimal seconds)	Creates a machine time duration on the POSIX scale.
static MachineTime<TimeUnit>	ofPosixUnits(long seconds, int fraction)	Creates a machine time duration on the POSIX scale.
static MachineTime<SI>	ofSISeconds(double seconds)	Creates a machine time duration on the UTC scale.
static MachineTime<SI>	ofSISeconds(BigDecimal seconds)	Creates a machine time duration on the UTC scale.
static MachineTime<SI>	ofSIUnits(long seconds, int fraction)	Creates a machine time duration on the UTC scale.
MachineTime<U>	plus(long amount, U unit)	Add given temporal amount to this machine time.
MachineTime<U>	plus(MachineTime<U> duration)	Add given temporal amount to this machine time.
<T extends TimePoint<? super U, T>> T	subtractFrom(T time)	Subtracts this time span from given time point.
static Collector<MachineTime<TimeUnit>,?,MachineTime<TimeUnit>>	summingUpPosix()	Helps to sum up durations of a stream.
static Collector<MachineTime<SI>,?,MachineTime<SI>>	summingUpReal()	Helps to sum up durations of a stream.
BigDecimal	toBigDecimal()	Converts this machine time duration into a decimal number of seconds.
String	toString()	Returns a format in technical notation including the name of the underlying time scale.
Duration	toTemporalAmount()	Converts this machine time to its JSR-310-equivalent.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Details

ON_POSIX_SCALE

public static final TimeMetric<TimeUnit,MachineTime<TimeUnit>> ON_POSIX_SCALE

Reversible metric on the POSIX scale (without leap seconds).

Since:

2.0

ON_UTC_SCALE

public static final TimeMetric<TimeUnit,MachineTime<SI>> ON_UTC_SCALE

Reversible metric on the UTC scale (inclusive leap seconds).

Time points before 1972 are not supported.

Since:

2.0

Method Details

of

public static MachineTime<TimeUnit> of(long amount,
 TimeUnit unit)

Creates a machine time duration on the POSIX scale.

Parameters:

amount - of units

unit - helps to interprete given amount

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

of

public static MachineTime<SI> of(long amount,
 SI unit)

Creates a machine time duration on the UTC scale.

Parameters:

amount - of units

unit - helps to interprete given amount

Returns:

new machine time duration

Since:

2.0

ofPosixUnits

public static MachineTime<TimeUnit> ofPosixUnits(long seconds,
 int fraction)

Creates a machine time duration on the POSIX scale.

Parameters:

seconds - POSIX-seconds

fraction - nanosecond part

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

ofSIUnits

public static MachineTime<SI> ofSIUnits(long seconds,
 int fraction)

Creates a machine time duration on the UTC scale.

Parameters:

seconds - SI-seconds

fraction - nanosecond part

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

ofPosixSeconds

public static MachineTime<TimeUnit> ofPosixSeconds(double seconds)

Creates a machine time duration on the POSIX scale.

Parameters:

seconds - decimal POSIX-seconds

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

IllegalArgumentException - if the argument is infinite or NaN

Since:

2.0

ofPosixSeconds

public static MachineTime<TimeUnit> ofPosixSeconds(BigDecimal seconds)

Creates a machine time duration on the POSIX scale.

Parameters:

seconds - decimal POSIX-seconds

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

ofSISeconds

public static MachineTime<SI> ofSISeconds(double seconds)

Creates a machine time duration on the UTC scale.

Parameters:

seconds - decimal SI-seconds

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

IllegalArgumentException - if the argument is infinite or NaN

Since:

2.0

ofSISeconds

public static MachineTime<SI> ofSISeconds(BigDecimal seconds)

Creates a machine time duration on the UTC scale.

Parameters:

seconds - decimal SI-seconds

Returns:

new machine time duration

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

getSeconds

public long getSeconds()

Yields the normalized seconds of this duration.

The normalization happens in case of a negative duration such that any fraction part falls into the range 0-999999999. In this case, following expression is NOT true: Math.abs(getSeconds()) == getPartialAmount(TimeUnit.SECONDS)

Returns:

long

See Also:

getFraction()

getFraction

public int getFraction()

Yields the normalized nanosecond fraction of this duration.

Returns:

nanosecond in range 0-999999999

See Also:

getSeconds()

getScale

public TimeScale getScale()

Yields the related time scale.

Returns:

either TimeScale.POSIX or TimeScale.UTC

Since:

2.0

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>

Returns:

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

contains

public boolean contains(Object 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>

Parameters:

unit - time unit to be asked (optional)

Returns:

true if exists else false

See Also:

getPartialAmount(U)

getPartialAmount

public long getPartialAmount(Object 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>

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>

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>

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>

Returns:

true if empty else false

plus

public MachineTime<U> plus(long amount,
 U unit)

Add given temporal amount to this machine time.

Parameters:

amount - the amount to be added

unit - the related time unit

Returns:

result of addition

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

plus

public MachineTime<U> plus(MachineTime<U> duration)

Add given temporal amount to this machine time.

Parameters:

duration - other machine time to be added

Returns:

result of addition

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

minus

public MachineTime<U> minus(long amount,
 U unit)

Subtracts given temporal amount from this machine time.

Parameters:

amount - the amount to be subtracted

unit - the related time unit

Returns:

difference result

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

minus

public MachineTime<U> minus(MachineTime<U> duration)

Subtracts given temporal amount from this machine time.

Parameters:

duration - other machine time to be subtracted

Returns:

difference result

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

abs

public MachineTime<U> abs()

Converts this machine duration to its absolute amount.

Returns:

absolute machine time duration, always non-negative

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

inverse

public MachineTime<U> inverse()

Creates a copy with inversed sign.

Returns:

negated machine time duration

Throws:

ArithmeticException - in case of numerical overflow

Since:

2.0

multipliedBy

public MachineTime<U> multipliedBy(long factor)

Multiplies this duration with given factor.

Parameters:

factor - multiplicand

Returns:

changed copy of this duration

multipliedBy

public MachineTime<U> multipliedBy(double factor)

Multiplies this duration with given decimal factor.

If more rounding control is needed then users might consider the alternatives multipliedBy(long) and dividedBy(long, RoundingMode).

Parameters:

factor - multiplicand

Returns:

changed copy of this duration

Throws:

IllegalArgumentException - if given factor is not a finite number

dividedBy

public MachineTime<U> dividedBy(long divisor,
 RoundingMode roundingMode)

Divides this duration by given divisor using given rounding mode.

Parameters:

divisor - divisor

roundingMode - rounding mode to be used in division

Returns:

changed copy of this duration

Since:

3.23/4.19

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>

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>

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)

summingUpPosix

public static Collector<MachineTime<TimeUnit>,?,MachineTime<TimeUnit>> summingUpPosix()

Helps to sum up durations of a stream.

A final normalization is automatically done.

Returns:

Collector for summing up durations in a stream

Since:

5.0

See Also:

Duration.summingUp(), summingUpReal()

summingUpReal

public static Collector<MachineTime<SI>,?,MachineTime<SI>> summingUpReal()

Helps to sum up durations of a stream.

A final normalization is automatically done.

Returns:

Collector for summing up durations in a stream

Since:

5.0

See Also:

Duration.summingUp(), summingUpPosix()

isShorterThan

public boolean isShorterThan(MachineTime<U> other)

Compares the absolute lengths and is equivalent to abs().compareTo(other.abs()) < 0.

Parameters:

other - another machine time to be compared with

Returns:

boolean

Since:

3.20/4.16

See Also:

compareTo(MachineTime), isLongerThan(MachineTime)

isLongerThan

public boolean isLongerThan(MachineTime<U> other)

Compares the absolute lengths and is equivalent to abs().compareTo(other.abs()) > 0.

Parameters:

other - another machine time to be compared with

Returns:

boolean

Since:

3.20/4.16

See Also:

compareTo(MachineTime), isShorterThan(MachineTime)

compareTo

public int compareTo(MachineTime<U> other)

Method of the Comparable-interface.

Specified by:

compareTo in interface Comparable<U>

Parameters:

other - another machine time to be compared with

Returns:

negative, zero or positive integer if this instance is shorter, equal or longer than other one

Throws:

ClassCastException - if this and the other machine time have different time scales

Since:

3.20/4.16

See Also:

isShorterThan(MachineTime), isLongerThan(MachineTime)

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Returns a format in technical notation including the name of the underlying time scale.

Overrides:

toString in class Object

Returns:

String like "-5s [POSIX]" or "4.123456789s [UTC]"

toBigDecimal

public BigDecimal toBigDecimal()

Converts this machine time duration into a decimal number of seconds.

Returns:

BigDecimal

toTemporalAmount

public Duration toTemporalAmount()

Converts this machine time to its JSR-310-equivalent.

Returns:

java.time.Duration

Throws:

IllegalStateException - if this instance is not based on java.util.concurrent.TimeUnit

Since:

4.28

See Also:

from(java.time.Duration)

from

public static MachineTime<TimeUnit> from(Duration threeten)

Converts given JSR-310-duration to a machine time.

Parameters:

threeten - duration defined in seconds and nanoseconds (JSR-310-API)

Returns:

MachineTime

Since:

4.28

See Also:

toTemporalAmount()