std/time/instant▲toc

Instants in time.

Instants use the mighty 128-bit ddoublestd/num/ddouble/ddouble: V timestamps to represent a durationstd/time/duration/duration: V since the epochstd/time/instant/epoch: instant. This gives very high range and precision (up 31 decimal digits). It spans about 10300 years into the past and future, well beyond the expected life span of the universe. Any time can be expressed with atto-second (10-18) precision up to about 300,000 years in the past and future, and with pico-second (10-12) precision any time since the age of the universe (about 13.8 billion years ago) up to 30 billion years into the future. For durations under 300 years, the precision is in excess of a zepto second (10-21). For comparison, it takes light about 500 zepto-seconds to travel the length of an hydrogen atom.

> instant(2100,1,1,0,0,0,1.0e-21).show(21)  // 1 zepto-second after Jan 1, 2100
"3155760037.000000000000000000001s"
> instant(300000,1,1,0,0,0,1.0e-18).show(18) // 1 atto-second after Jan 1, 300000
"9403971696037.000000000000000001s"
> instant(-13.82e9.int,1,1,0,0,0,1.0e-12).show(12) // 1 pico-second after the birth of the universe
"-436117139753903999.999999999999s"
> instant(2100,1,1,0,0,0,1.0e-21).show(21)  // 1 zepto-second after Jan 1, 2100
"3155760037.000000000000000000001s"
> instant(300000,1,1,0,0,0,1.0e-18).show(18) // 1 atto-second after Jan 1, 300000
"9403971696037.000000000000000001s"
> instant(-13.82e9.int,1,1,0,0,0,1.0e-12).show(12) // 1 pico-second after the birth of the universe
"-436117139753903999.999999999999s"

Internally, instants are represented in a certain time scale (timescalestd/time/instant/timescale: V) for efficiency and precision. They automatically convert between different time scales when necessary (for example when comparing instants in time, or calculating durations between UTC calendar times).

Time durations (durationstd/time/duration/duration: V) are always in SI seconds (as measured on the Earth's geoid).

References

[1]Claudine Thomas, The Accuracy of TAI. Proceedings of the 29th Annual Precise Time and Time Interval Systems and Applications Meeting, Long Beach, California, December 1997, pp. 19–26. pdf 🔎

.

Represents a precise instant in time.

Internally, instants are represented in a certain time scale (timescalestd/time/instant/timescale: V) for efficiency and precision. They automatically convert between different time scales when necessary (for example when comparing instants in time, or calculating durations between UTC calendar times).

Add a duration to an instant in time. Note: this generally entails conversion to TAI time (ts-taistd/time/instant/ts-tai: timescale). See also add-duration-instd/time/instant/add-duration-in: (i : instant, tscale : timescale, t : timespan) -> instant and add-days to add in direct time scale units.

Return the duration between to instants in time.

Add a duration of t seconds of time scale tscale. This can for example be used to add Unix or NTP seconds where leap seconds are ignored (allthough it is recommended in that case to use time and add logical days etc).

> instant(2005,12,31).add-duration-in( ts-unix, (24*3600).timespan ).time
2006-01-01T00:00:00Z

> (instant(2005,12,31) + 24.hours).time 2005-12-31T23:59:60Z > instant(2005,12,31).add-duration-instd/time/instant/add-duration-in: (i : instant, tscale : timescale, t : timespan) -> instant( ts-unix, (24*3600).timespan ).time 2006-01-01T00:00:00Z

> (instant(2005,12,31) + 24.hours).time 2005-12-31T23:59:60Z

.

Return days since 2000-01-01 in the time scale of the instant.

Return days since 2000-01-01 in the time scale of the instant, together with the clock on that day.

Return the (TAI) SI second duration since the epochstd/time/instant/epoch: instant at this instant.

Our epoch is set at 2000-01-01 TAI (which is equal to 1999-12-31T23:59:28Z UTC).
Another candidate epoch could have been the standard J2000 epoch (epoch-j2000), which equals 2000-01-01T12:00:00 TT (terrestrial time). However, that would mean that for the most common time scales, namely UTC and TAI, there would always be a fractional offset (of 32.184s) for common time stamps. Moreover, by having an epoch at noon there would be an extra correction needed for calendar date calculations too.
Similarly, the standard Unix epoch of 1970-01-01Z UTC is not ideal either since the UTC offset with TAI was fractional at that time (namely 8.000082s).
Finally, after 1996, TAI was corrected for black-body radiation [1] which makes the 2000-01-01 epoch a very precisely defined point in time.

Create an instant from a raw GPS time since the GPS epoch (1980-01-06Z).

Create an instant from a GPS time in weeks and SI seconds since the GPS epoch (1980-01-06Z).

Get the GPS time in SI seconds since the GPS epoch (1980-01-06Z).

Get the GPS time as weeks and SI seconds in the week since the GPS epoch (1980-01-06Z).

Create an instant from a time stamp t interpreted in time scale tsstd/time/instant/ts: (instant : instant) -> timescale.
Be careful to ensure that t should indeed be interpreted in the given time scale.

Return the instant at (TAI) SI seconds duration since the epochstd/time/instant/epoch: instant.

Return the julian day in a given time scale tsstd/time/instant/ts: (instant : instant) -> timescale for an instant i. Properly takes leap seconds into account when calculating the fraction of the day in a UTC calendar. For example:

> time(2014,12,31,23,59,59).jd
2457023.499988425925926

> time(2015,12,31,23,59,59).jd
2457388.499988425925926

> time(2016,12,31,23,59,59).jd
2457754.499976852119767

> time(2016,12,31,23,59,60).jd
2457754.499988426059884

.

Return the modified julian day in a given time scale tsstd/time/instant/ts: (instant : instant) -> timescale for an instant i. Can also pass an optional delta (=timespan0std/time/timestamp/timespan0: timespan) that is added to the raw timestamp of i before conversion (used in std/time/time to take timezones into account).

Round an instant to a certain precision (prec is number of digits of the fraction of the second).
Takes special care for instants that use a UTC timescale to round into leap seconds if appropriate.

The seconds in the day of instant i (in its time scale).

Show an instant as a number of (TAI) SI seconds since the epochstd/time/instant/epoch: instant in a given precision. This can be used as an unambigious time stamp.

Internal: show an instant as a raw timestamp in a given precision, postfixed with the time scale name.

Get the TT time in SI seconds since the TT epoch (1977-01-01 TAI).

Create an instant from a raw TT time since the TT epoch (1977-01-01 TAI).

Change the internal representation of an instant to use another timescale. Only used in special cases for efficiency. For example, when comparing an instant in TAI time to thousands of UTC times, it is more efficient to convert the TAI time to UTC first to avoid converting at each comparision.

A time scale defines how time is measured: the rate and unit of time, and how it can be converted to- and from TAI.
For time calculations, usually the TAI (international atomic time) time scale (ts-taistd/time/instant/ts-tai: timescale) is used which is time measured as SI seconds on the Earths geoid. Another common time scale is UTC (std/time/utc/ts-utc) which also uses SI second time units but can contain leap seconds.

Does this timescale have leap seconds?

Create a new time scale based on SI seconds (as measured on the Earth's geoid) with a given namestd/time/instant/name: (timescale : timescale) -> string, a fixed offset (=duration0std/time/duration/duration0: duration) from TAI (e.g. GPS = TAI - 19), and a epoch-y2k (= timestamp0std/time/timestamp/timestamp0: timestamp) which is the timestamp of the 2000-01-01 date in that timescale e.g. for a timescale tsstd/time/instant/ts: (instant : instant) -> timescale:
epoch-y2k = instant(2000,1,1,cal=iso-calendar(tsstd/time/instant/ts: (instant : instant) -> timescale)).since-in(tsstd/time/instant/ts: (instant : instant) -> timescale).

Return the time scale that instant i uses.

The GPS time scale based on SI seconds with a 1980-01-06 GPS epoch.
GPS = TAI - 19s.

The TAI (International atomic time) time scale is based on SI seconds measured on the Earth's geoid, with a 2000-01-01 TAI epochstd/time/instant/epoch: instant.

The TT (Terrestrial time) time scale is based on SI seconds with a 1977-01-01 TAI epochstd/time/instant/epoch: instant. It is the continuation of TDT (Terrestrial dynamic time) and ET (Ephemeris time). TT is defined as: TT = TAI + 32.184s.

Show a timestamp with an optional maximum precision (max-prec (=9)) and minimum width for the seconds (=1).