MachineTime (Time4J-Base 5.8 API)

java.lang.Object
- net.time4j.MachineTime

Type Parameters:

U - either TimeUnit or SI

All Implemented Interfaces:

Serializable, Comparable<MachineTime>, TimeSpan
```
public final class MachineTime
extends Object
implements TimeSpan, Comparable<MachineTime>, 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

Concurrency:
This class is immutable and can be used by multiple threads in parallel.

Nested Class Summary

Nested Classes
Modifier and Type	Class and 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

Field Summary

Fields
Modifier and Type	Field and 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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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<SI>`	`of(long amount, SI unit)` Creates a machine time duration on the UTC scale.
`static MachineTime<TimeUnit>`	`of(long amount, TimeUnit unit)` 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>`	`ofPosixSeconds(double 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(BigDecimal seconds)` Creates a machine time duration on the UTC scale.
`static MachineTime<SI>`	`ofSISeconds(double 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 Detail
 - 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 Detail
 - 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> 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
 
 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
 
 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
 
 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
 
 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
 
 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
 
 Returns:
 
 true if empty else false
 - plus
```
public MachineTime 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 plus(MachineTime 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 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 minus(MachineTime 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 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 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 multipliedBy(long factor)
```
 Multiplies this duration with given factor.
 
 Parameters:
 
 factor - multiplicand
 
 Returns:
 
 changed copy of this duration
 - multipliedBy
```
public MachineTime 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 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
 
 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
 
 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 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 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 other)
```
 Method of the Comparable-interface.
 
 Specified by:
 
 compareTo in interface Comparable<MachineTime>
 
 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()

Class MachineTime<U>

Nested Class Summary

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

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ON_POSIX_SCALE

ON_UTC_SCALE

Method Detail

of

of

ofPosixUnits

ofSIUnits

ofPosixSeconds

ofPosixSeconds

ofSISeconds

ofSISeconds

getSeconds

getFraction

getScale

getTotalLength

contains

getPartialAmount

isNegative

isPositive

isEmpty

plus

plus

minus

minus

abs

inverse

multipliedBy

multipliedBy

dividedBy

addTo

subtractFrom

summingUpPosix

summingUpReal

isShorterThan

isLongerThan

compareTo

equals

hashCode

toString

toBigDecimal

toTemporalAmount

from