bin_io and sexp representations of Zone.t are the name of the zone, and not the full
data that is read from disk when Zone.find is called. The full Zone.t is
reconstructed on the receiving/reading side by reloading the zone file from disk. Any
zone name that is accepted by
find is acceptable in the bin_io and sexp
val find :
string -> t option
find namelooks up a
tby its name and returns it.
val find_office :
[ `chi | `hkg | `ldn | `nyc ] -> t
find_office officea more type-safe interface for pulling timezones related to existing Jane Street offices/locations.
val find_exn :
string -> t
val machine_zone :
?refresh:bool -> unit -> t
machine_zone ?refresh () returns the machines zone (t). It does this by first
looking for a value in the environment variable "TZ", and loading the named zone if it
is set. If "TZ" is not set it reads /etc/localtime directly.
The first call to machine_zone is cached, so there is no need to cache it locally. The cache can be bypassed and refreshed by setting ~refresh to true.
Note that this function can throw an exception if the TZ time variable is misconfigured or if the appropriate timezone files can't be found because of the way the box is configured. We don't put an _exn on this function because that misconfiguration is quite rare.
val local :
localis the result of
machine_zone (), taken the first time it is demanded. It may be difficult to know exactly when that happens, so
localshould be avoided in applications that expect TZ or /etc/localtime to change during program operation.
Arguably, changing the timezone of a running program is a problematic operation anyway -- most people write code assuming the clock doesn't suddenly jump back several hours without warning.
val likely_machine_zones :
string list ref
likely_machine_zonesis a list of zone names that will be searched first when trying to determine the machine zone of a box. Setting this to a likely set of zones for your application will speed the very first call to machine_zone
val of_utc_offset :
hours:int -> t
of_utc_offset offsetreturns a timezone with a static UTC offset (given in hours).
val default_utc_offset_deprecated :
t -> int
default_utc_offsetreturns the UTC offset of default regime for timezone
tin seconds. Note: the default utc offset may not reflect the current utc offset.
val utc :
utcthe UTC time zone. Included for convenience
val abbreviation :
t -> float -> string
abbreviation zone treturns t abbreviation name such as EDT, EST, JST of given
zoneat the time
t. This string conversion is one-way only, and cannot reliably be turned back into a t
val name :
t -> string
name zonereturns the name of the time zone
val init :
unit -> unit
init ()pre-load all available time zones from disk, this function has no effect if it is called multiple times. Time zones will otherwise be loaded at need from the disk on the first call to find/find_exn.
val digest :
t -> string option
digest treturn the MD5 digest of the file the t was created from (if any)
val initialized_zones :
unit -> (string * t) list
initialized_zones ()returns a sorted list of time zone names that have been loaded from disk thus far.
val shift_epoch_time :
t -> [ `Local | `UTC ] -> float -> float
shift_epoch_time zone [`Local | `UTC] timeTakes an epoch (aka "unix") time given either in local or in UTC (as indicated in the arguments) and shifts it according to the local time regime in force in zone. That is, given a Local epoch time it will return the corresponding UTC timestamp and vice versa. This function is low level, and is not intended to be called by most client code. Use the high level functions provided in Time instead.
val next_clock_shift :
t -> after:Time_internal.T.t -> (Time_internal.T.t * Span.t) option
Time.tand returns the next
Time.t, if any, that the time zone UTC offset changes, and by how much it does so.
exception Unknown_zone of
exception Invalid_file_format of
module Stable :
module V1 :
val t_of_sexp :
Sexplib.Sexp.t -> t
val sexp_of_t :
t -> Sexplib.Sexp.t
val bin_t :
val bin_read_t :
val __bin_read_t__ :
(int -> t) Core_kernel.Std.Bin_prot.Read.reader
val bin_reader_t :
val bin_size_t :
val bin_write_t :
val bin_writer_t :
This library replicates and extends the functionality of the standard Unix time handling functions (currently exposed in the Unix module, and indirectly through the Time module).
Things you should know before delving into the mess of time...
general overview - http://www.twinsun.com/tz/tz-link.htm zone abbreviations - http://blogs.msdn.com/oldnewthing/archive/2008/03/07/8080060.aspx leap seconds - http://en.wikipedia.org/wiki/Leap_second epoch time - http://en.wikipedia.org/wiki/Unix_time UTC/GMT time - http://www.apparent-wind.com/gmt-explained.html TAI time - http://en.wikipedia.org/wiki/International_Atomic_Time Almost every possible time measurement - http://www.ucolick.org/~sla/leapsecs/timescales.html
for more information on the obscure forms. The common form represents a relative path from the base /usr/share/zoneinfo/posix, and is generally in the form of a continent or country name paired with a city name (Europe/London, America/New_York). This is used to load the specified file from disk, which contains a time zone database in zic format (man tzfile).
One common misconception about time zones is that the standard time zone abbreviations can be used. For instance, EST surely refers to Eastern Standard Time. This is unfortunately not true - CST can refer to China Central Time, Central Standard Time, or Cuba Summer Time for instance - and time zone libraries that appear to correctly parse times that use time zone abbreviations do so by using a heuristic that usually assumes you mean a time in the US or Europe, in that order. Time zones also sometimes use two different abbreviations depending on whether the time in question is in standard time, or daylight savings time. These abbreviations are kept in the timezone databases, which is how programs like date manage to output meaningful abbreviations, it is only reading in times with abbreviations that is poorly specified.
This library contains a function that attempts to make an accurate determination of the machine timezone by testing the md5 sum of the currently referenced timezone file against all of the possible candidates in the system database. It additionally makes some adjustments to return the more common timezone names since some files in the database are duplicated under several names. It returns an option because of the problems mentioned above.
There are two cases where string time conversions are problematic, both related to daylight savings time.
In the case where time jumps forward one hour, there are possible representations of times that never happened 2006-04-02T02:30:00 in the eastern U.S. never happened for instance, because the clock jumped forward one hour directly from 2 to 3. Unix time zone libraries asked to convert one of these times will generally produce the epoch time that represents the time 1/2 hour after 2 am, which when converted back to a string representation will be T03:30:00.
The second case is when the clocks are set back one hour, which causes one hour of time to happen twice. Converting a string in this range without further specification into an epoch time is indeterminate since it could be referring to either of two times. Unix libraries handle this by either allowing you to pass in a dst flag to the conversion function to specify which time you mean, or by using a heuristic to guess which time you meant.
The existence of both cases make a strong argument for serializing all times in UTC, which doesn't suffer from these issues.