# 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).

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

Create an instant given a julian day and time scale `ts` .

Create an instant given a modified julian day. and time scale `ts`.
`modified-julian-day = julian-day - 2400000.5`.

Subtract a duration from an instant in time.

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

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

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

Create an instant given a julian day.

Create an instant given a modified julian day. and time scale `ts`.
`modified-julian-day = julian-day - 2400000.5`.

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

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.

Return the time scale that instant `i` uses.

Return `timestampstd/time/timestamp/timestamp: V` since 2000-01-01 in the time scale of the instant.

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

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 `days` days to the instant.

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
```
.

Compare two `instantstd/time/instant/instant: V`s in time.

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.

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.

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).

Return the julian day in a given time scale `ts` 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``````

.

The maximum of two instants.

The minimum of two instants.

Return the modified julian day in a given time scale `ts` 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 `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).

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

Return a `timestampstd/time/timestamp/timestamp: V` for instant `i` in a certain time scale `tscale`.

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 (`ts-utc`) which also uses SI second time units but can contain leap seconds.

Return the instant in time scale `ts`, `days` and `secs` after 2000-01-01 in that timescale.

Are two timescales the same?

Create an instant from a time stamp `t` interpreted in time scale `ts`.
Be careful to ensure that `t` should indeed be interpreted in the given time scale.

Automatically generated. Retrieves the `name` constructor field of the `timescalestd/time/instant/timescale: V` type.

Given a `durationstd/time/duration/duration: V` since the `epochstd/time/instant/epoch: instant`, return a `timespanstd/time/timestamp/timespan: V` for that instant in time scale `ts`.

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 `name`, 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 `ts`:
`epoch-y2k = instant(2000,1,1,cal=iso-calendar(ts)).since-in(ts)`.

Create a new time scale given `name`, two inverse function `from-taistd/time/instant/from-tai: (ts : timescale, d : duration) -> timestamp` and `to-taistd/time/instant/to-tai: (ts : timescale, t : timestamp) -> duration`, and an optional function that returns the seconds in the day of the instant. The time unit defaults to `name`.

Return the `durationstd/time/duration/duration: V` since the `epochstd/time/instant/epoch: instant` for a timestamp `t` interpreted in time scale `ts`.

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`).