public final class TaiInstant extends Object implements Comparable<TaiInstant>, Serializable
The java.time
classes use the Java time-scale for simplicity.
That scale works on the assumption that the time-line is simple, there are no leap-seconds
and there are always 24 * 60 * 60 seconds in a day. Unfortunately, the Earth's rotation
is not straightforward, and a solar day does not match this definition.
This class is an alternative representation based on the TAI time-scale. TAI is a single incrementing count of SI seconds. There are no leap seconds or other discontinuities.
As a result of the simple definition, this time-scale would make an excellent timestamp. However, there are, at the time of writing, few easy ways to obtain an accurate TAI instant, but it is relatively easy to obtain a GPS instant. GPS and TAI differ by the fixed amount of 19 seconds.
The duration between two points on the TAI time-scale is calculated solely using this class.
Do not use the between
method on Duration
as that will lose information.
Instead use durationUntil(TaiInstant)
on this class.
It is intended that most applications will use the Instant
class
which uses the UTC-SLS mapping from UTC to guarantee 86400 seconds per day.
Specialist applications with access to an accurate time-source may find this class useful.
The TAI time-scale is a very simple well-regarded representation of time.
The scale is defined using atomic clocks counting SI seconds.
It has proceeded in a continuous uninterrupted manner since the defined
epoch of 1958-01-01T00:00:00(TAI)
.
There are no leap seconds or other discontinuities.
This class may be used for instants in the far past and far future. Since some instants will be prior to 1958, it is not strictly an implementation of TAI. Instead, it is a proleptic time-scale based on TAI and equivalent to it since 1958.
This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.
Modifier and Type | Method and Description |
---|---|
int |
compareTo(TaiInstant otherInstant)
Compares this instant to another based on the time-line.
|
java.time.Duration |
durationUntil(TaiInstant otherInstant)
Returns the duration between this instant and the specified instant.
|
boolean |
equals(Object otherInstant)
Checks if this instant is equal to the specified
TaiInstant . |
int |
getNano()
Gets the number of nanoseconds, later along the time-line, from the start
of the second.
|
long |
getTaiSeconds()
Gets the number of seconds from the TAI epoch of 1958-01-01T00:00:00(TAI).
|
int |
hashCode()
Returns a hash code for this instant.
|
TaiInstant |
minus(java.time.Duration duration)
Returns a copy of this instant with the specified duration subtracted.
|
static TaiInstant |
of(java.time.Instant instant)
Obtains an instance of
TaiInstant from an Instant . |
static TaiInstant |
of(UtcInstant instant)
Obtains an instance of
TaiInstant from a UtcInstant . |
static TaiInstant |
ofTaiSeconds(long taiSeconds,
long nanoAdjustment)
Obtains an instance of
TaiInstant from the number of seconds from
the TAI epoch of 1958-01-01T00:00:00(TAI) with a nanosecond fraction of second. |
static TaiInstant |
parse(CharSequence text)
Obtains an instance of
TaiInstant from a text string. |
TaiInstant |
plus(java.time.Duration duration)
Returns a copy of this instant with the specified duration added.
|
java.time.Instant |
toInstant()
Converts this instant to an
Instant . |
String |
toString()
A string representation of this instant.
|
UtcInstant |
toUtcInstant()
Converts this instant to a
UtcInstant . |
TaiInstant |
withNano(int nanoOfSecond)
Returns a copy of this
TaiInstant with the nano-of-second value changed. |
TaiInstant |
withTaiSeconds(long taiSeconds)
Returns a copy of this
TaiInstant with the number of seconds
from the TAI epoch of 1958-01-01T00:00:00(TAI). |
public static TaiInstant ofTaiSeconds(long taiSeconds, long nanoAdjustment)
TaiInstant
from the number of seconds from
the TAI epoch of 1958-01-01T00:00:00(TAI) with a nanosecond fraction of second.
This method allows an arbitrary number of nanoseconds to be passed in. The factory will alter the values of the second and nanosecond in order to ensure that the stored nanosecond is in the range 0 to 999,999,999. For example, the following will result in the exactly the same instant:
TaiInstant.ofTaiSeconds(3, 1); TaiInstant.ofTaiSeconds(4, -999999999); TaiInstant.ofTaiSeconds(2, 1000000001);
taiSeconds
- the number of seconds from the epoch of 1958-01-01T00:00:00(TAI)nanoAdjustment
- the nanosecond adjustment to the number of seconds, positive or negativeArithmeticException
- if numeric overflow occurspublic static TaiInstant of(java.time.Instant instant)
TaiInstant
from an Instant
.
Converting a UTC-SLS instant to TAI requires leap second rules. This method uses the latest available system rules. The conversion first maps from UTC-SLS to UTC, then converts to TAI.
Conversion from an Instant
will not be completely accurate near
a leap second in accordance with UTC-SLS.
instant
- the instant to convert, not nulljava.time.DateTimeException
- if the range of TaiInstant
is exceededArithmeticException
- if numeric overflow occurspublic static TaiInstant of(UtcInstant instant)
TaiInstant
from a UtcInstant
.
Converting a UTC instant to TAI requires leap second rules. This method uses the latest available system rules.
The TaiInstant
will represent exactly the same point on the
time-line as per the available leap-second rules.
If the leap-second rules change then conversion back to UTC may
result in a different instant.
instant
- the instant to convert, not nulljava.time.DateTimeException
- if the range of TaiInstant
is exceededArithmeticException
- if numeric overflow occurspublic static TaiInstant parse(CharSequence text)
TaiInstant
from a text string.
The following format is accepted:
{seconds}.{nanosOfSecond}s(TAI)
The accepted format is strict.
The seconds part must contain only numbers and a possible leading negative sign.
The nanoseconds part must contain exactly nine digits.
The trailing literal must be exactly specified.
This format parses the toString
format.
text
- the text to parse such as "12345.123456789s(TAI)", not nulljava.time.format.DateTimeParseException
- if the text cannot be parsedpublic long getTaiSeconds()
The TAI second count is a simple incrementing count of seconds where
second 0 is 1958-01-01T00:00:00(TAI).
The nanosecond part of the day is returned by getNanosOfSecond
.
public TaiInstant withTaiSeconds(long taiSeconds)
TaiInstant
with the number of seconds
from the TAI epoch of 1958-01-01T00:00:00(TAI).
The TAI second count is a simple incrementing count of seconds where
second 0 is 1958-01-01T00:00:00(TAI).
The nanosecond part of the day is returned by getNanosOfSecond
.
This instance is immutable and unaffected by this method call.
taiSeconds
- the number of seconds from the epoch of 1958-01-01T00:00:00(TAI)TaiInstant
based on this instant with the requested second, not nullpublic int getNano()
The nanosecond-of-second value measures the total number of nanoseconds from
the second returned by getTaiSeconds()
.
public TaiInstant withNano(int nanoOfSecond)
TaiInstant
with the nano-of-second value changed.
The nanosecond-of-second value measures the total number of nanoseconds from
the second returned by getTaiSeconds()
.
This instance is immutable and unaffected by this method call.
nanoOfSecond
- the nano-of-second, from 0 to 999,999,999TaiInstant
based on this instant with the requested nano-of-second, not nullIllegalArgumentException
- if nanoOfSecond is out of rangepublic TaiInstant plus(java.time.Duration duration)
The duration is added using simple addition of the seconds and nanoseconds in the duration to the seconds and nanoseconds of this instant. As a result, the duration is treated as being measured in TAI compatible seconds for the purpose of this method.
This instance is immutable and unaffected by this method call.
duration
- the duration to add, not nullTaiInstant
based on this instant with the duration added, not nullArithmeticException
- if the calculation exceeds the supported rangepublic TaiInstant minus(java.time.Duration duration)
The duration is subtracted using simple subtraction of the seconds and nanoseconds in the duration from the seconds and nanoseconds of this instant. As a result, the duration is treated as being measured in TAI compatible seconds for the purpose of this method.
This instance is immutable and unaffected by this method call.
duration
- the duration to subtract, not nullTaiInstant
based on this instant with the duration subtracted, not nullArithmeticException
- if the calculation exceeds the supported rangepublic java.time.Duration durationUntil(TaiInstant otherInstant)
This calculates the duration between this instant and another based on
the TAI time-scale. Adding the duration to this instant using plus(java.time.Duration)
will always result in an instant equal to the specified instant.
otherInstant
- the instant to calculate the duration until, not nullArithmeticException
- if the calculation exceeds the supported rangepublic java.time.Instant toInstant()
Instant
.
Converting a TAI instant to UTC-SLS requires leap second rules. This method uses the latest available system rules. The conversion first maps from TAI to UTC, then converts to UTC-SLS.
Conversion to an Instant
will not be completely accurate near
a leap second in accordance with UTC-SLS.
Instant
representing the best approximation of this instant, not nulljava.time.DateTimeException
- if the range of Instant
is exceededArithmeticException
- if numeric overflow occurspublic UtcInstant toUtcInstant()
UtcInstant
.
Converting a TAI instant to UTC requires leap second rules. This method uses the latest available system rules.
The UtcInstant
will represent exactly the same point on the
time-line as per the available leap-second rules.
If the leap-second rules change then conversion back to TAI may
result in a different instant.
UtcInstant
representing the same instant, not nulljava.time.DateTimeException
- if the range of UtcInstant
is exceededArithmeticException
- if numeric overflow occurspublic int compareTo(TaiInstant otherInstant)
compareTo
in interface Comparable<TaiInstant>
otherInstant
- the other instant to compare to, not nullpublic boolean equals(Object otherInstant)
TaiInstant
.public int hashCode()
public String toString()
The string is formatted as {seconds).(nanosOfSecond}s(TAI)
.
At least one second digit will be present.
The nanoseconds will always be nine digits.
Copyright © 2010–2014 ThreeTen.org. All rights reserved.