A fully qualified point in time, independent of timezone.
Sexp conversions use the local timezone by default. This can be overridden by calling
Time_ns, this module purposely omits
1. They produce unintuitive corner cases because most people's mental models of time
do not include +/- infinity as concrete values
2. In practice, when people ask for these values, it is for questionable uses, e.g.,
as null values to use in place of explicit options.
midnight, Jan 1, 1970 in UTC
add t s adds the span
s to time
t and returns the resulting time.
NOTE: adding spans as a means of adding days is not accurate, and may run into trouble due to shifts in daylight savings time, float arithmetic issues, and leap seconds. See the comment at the top of Zone.mli for a more complete discussion of some of the issues of time-keeping. For spans that cross date boundaries, use date functions instead.
All these conversion functions use the current time zone. Unless marked _utc, in which case they use Universal Coordinated Time
Because timezone offsets change throughout the year (clocks go forward or back) some
local times can occur twice or not at all. In the case that they occur twice, this
`Twice with both occurrences in order; if they do not occur at all,
this function gives
`Never with the time at which the local clock skips over the
desired time of day.
Note that this is really only intended to work with DST transitions and not unusual or dramatic changes, like the calendar change in 1752 (run "cal 9 1752" in a shell to see). In particular it makes the assumption that midnight of each day is unambiguous.
Always returns the
Date.t * Ofday.t that
to_date_ofday would have returned, and in
addition returns a variant indicating whether the time is associated with a time zone
- `Only -> there is a one-to-one mapping between [t]'s and [Date.t * Ofday.t] pairs - `Also_at -> there is another [t] that maps to the same [Date.t * Ofday.t] (this date/time pair happened twice because the clock fell back) - `Also_skipped -> there is another [Date.t * Ofday.t] pair that never happened (due to a jump forward) that [of_date_ofday] would map to the same [t].
to_string_abs ~zone t returns a string that represents an absolute time, rather than
a local time with an assumed time zone. This string can be round-tripped, even on a
machine in a different time zone than the machine that wrote the string.
The string will display the date and of-day of
zone together with
zone as an
offset from UTC.
to_string_abs_trimmed is the same as
to_string_abs, but drops trailing seconds and
milliseconds if they are 0.
Note that the difference between
to_string_abs is not that one
returns an absolute time and one doesn't, but that
to_string_abs lets you specify
the time zone, while
to_string takes it to be the local time zone.
of_string_abs s is like
of_string, but demands that
s indicate the timezone the
time is expressed in.
pause span sleeps for span time.
pause_forever sleeps indefinitely.
occurrence side time ~ofday ~zone returns a
Time.t that is the occurrence of ofday
(in the given
zone) that is the latest occurrence (<=)
time or the earliest
time, according to
NOTE: If the given time converted to wall clock time in the given zone is equal to ofday then the t returned will be equal to the t given.
format t fmt formats the given time according to fmt, which follows the formatting
rules given in 'man strftime'. The time is output in the given timezone.
%Y - year (4 digits) %y - year (2 digits) %m - month %d - day %H - hour %M - minute %S - second
a common choice would be: %Y-%m-%d %H:%M:%S
to_epoch t returns the number of seconds since Jan 1, 1970 00:00:00 in UTC