16 Time Zones and UTC Offsets

6.2.901.900

16 Time Zones and UTC Offsets

value
tz/c : flat-contract?

A time zone, in Gregor, is either:

an identifier from the IANA tz database, like "America/New_York" or "Antarctica/Troll", or
an offset from UTC in seconds, expressed as an exact integer between -64800 and 64800.

parameter
(current-timezone) → tz/c
(current-timezone tz) → void?
tz : tz/c
= (system-tzid)

A parameter that defines the current time zone. The current time zone is used as a default value in many Gregor functions, including moment and all of the clock functions that rely on the current moment.

16.1 Resolving UTC Offsets

Many time zones introduce discontinuities in the local time-line. In time zones that use daylight saving time (DST), the transition from standard time to DST introduces a gap in the time-line when the local time jumps ahead by an hour. Similarly, the transition back to standard time introduces an overlap when the clock is set back and the same hour is repeated, only with a different UTC offset.

Whenever a Gregor function might construct a moment that falls into a gap or an overlap, the function will accept an optional keyword argument named #:resolve-offset. The argument value must be an offset resolver, a function satisfying the offset-resolver/c contract.

An offset resolver comprises a gap resolver and an overlap resolver, functions that satisfy gap-resolver/c and overlap-resolver/c, respectively.

Most functions that take a #:resolve-offset parameter use resolve-offset/raise as the default value. This is a simple offset resolver that raises exn:gregor:invalid-offset whenever it encounters either a gap or an overlap.

16.1.1 Offset Resolvers

value
offset-resolver/c : chaperone-contract?

A contract for offset resolver functions. The contract is specified as:

(-> (or/c tzgap? tzoverlap?)
    datetime?
    string?
    (or/c moment? #f)
    moment?)

procedure
(offset-resolver gap-resolver
overlap-resolver) → offset-resolver/c
gap-resolver : gap-resolver/c
overlap-resolver : overlap-resolver/c

Constructs an offset resolver from the given gap-resolver and overlap resolver.

procedure
(resolve-offset/raise gap-or-overlap
local
tzid
orig) → moment?
  gap-or-overlap : (or/c tzgap? tzoverlap?)
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

An offset resolver that unconditionally raises exn:gregor:invalid-offset.

Examples:

> (moment 2015 3 8 2 30 #:tz "America/New_York" ; in gap
#:resolve-offset resolve-offset/raise)
Illegal moment: local time 2015-03-08T02:30:00 does not
exist in time zone America/New_York
> (moment 2015 11 1 1 30 #:tz "America/New_York" ; in overlap
#:resolve-offset resolve-offset/raise)
Illegal moment: local time 2015-11-01T01:30:00 is ambiguous
in time zone America/New_York

procedure
(resolve-offset/pre gap-or-overlap
local
tzid
orig) → moment?
  gap-or-overlap : (or/c tzgap? tzoverlap?)
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

An offset resolver that combines resolve-gap/pre and resolve-overlap/pre.

Examples:

> (moment 2015 3 8 2 30 #:tz "America/New_York" ; in gap
#:resolve-offset resolve-offset/pre)
#<moment 2015-03-08T01:59:59.999999999-05:00[America/New_York]>
> (moment 2015 11 1 1 30 #:tz "America/New_York" ; in overlap
#:resolve-offset resolve-offset/pre)
#<moment 2015-11-01T01:30:00-04:00[America/New_York]>

procedure
(resolve-offset/post gap-or-overlap
local
tzid
orig) → moment?
  gap-or-overlap : (or/c tzgap? tzoverlap?)
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

An offset resolver that combines resolve-gap/post and resolve-overlap/post.

Examples:

> (moment 2015 3 8 2 30 #:tz "America/New_York" ; in gap
#:resolve-offset resolve-offset/post)
#<moment 2015-03-08T03:00:00-04:00[America/New_York]>
> (moment 2015 11 1 1 30 #:tz "America/New_York" ; in overlap
#:resolve-offset resolve-offset/post)
#<moment 2015-11-01T01:30:00-05:00[America/New_York]>

procedure
(resolve-offset/post-gap/pre-overlap gap-or-overlap
local
tzid
orig) → moment?
  gap-or-overlap : (or/c tzgap? tzoverlap?)
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

An offset resolver that combines resolve-gap/post and resolve-overlap/pre.

Examples:

> (moment 2015 3 8 2 30 #:tz "America/New_York" ; in gap
#:resolve-offset resolve-offset/post-gap/pre-overlap)
#<moment 2015-03-08T03:00:00-04:00[America/New_York]>
> (moment 2015 11 1 1 30 #:tz "America/New_York" ; in overlap
#:resolve-offset resolve-offset/post-gap/pre-overlap)
#<moment 2015-11-01T01:30:00-04:00[America/New_York]>

procedure
(resolve-offset/retain gap-or-overlap
local
tzid
orig) → moment?
  gap-or-overlap : (or/c tzgap? tzoverlap?)
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

An offset resolver that combines resolve-gap/post and resolve-overlap/retain.

This resolver is used by default in date arithmetic functions.

Examples:

> (+years
   (moment 2014 11 1 1 30 #:tz "America/New_York") ; UTC-04:00
   1
   #:resolve-offset resolve-offset/retain)
#<moment 2015-11-01T01:30:00-04:00[America/New_York]>
> (+years
   (moment 2014 11 1 1 30 #:tz "America/New_York") ; UTC-04:00
   1
   #:resolve-offset resolve-offset/post)
#<moment 2015-11-01T01:30:00-05:00[America/New_York]>

procedure
(resolve-offset/push gap-or-overlap
local
tzid
orig) → moment?
  gap-or-overlap : (or/c tzgap? tzoverlap?)
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

An offset resolver that combines resolve-gap/push and resolve-overlap/post.

Examples:

> (moment 2015 3 8 2 30 #:tz "America/New_York" ; in gap
#:resolve-offset resolve-offset/push)
#<moment 2015-03-08T03:30:00-04:00[America/New_York]>
> (moment 2015 11 1 1 30 #:tz "America/New_York" ; in overlap
#:resolve-offset resolve-offset/push)
#<moment 2015-11-01T01:30:00-05:00[America/New_York]>

16.1.2 Gap Resolvers

value
gap-resolver/c : chaperone-contract?

A contract for gap resolver functions. The contract is specified as:

(-> tzgap?
    datetime?
    string?
    (or/c moment? #f)
    moment?)

procedure
(resolve-gap/pre gap local tzid orig) → moment?
  gap : tzgap?
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

Returns the moment just prior to the given gap.

procedure
(resolve-gap/post gap local tzid orig) → moment?
  gap : tzgap?
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

Returns the moment at the end of the given gap.

procedure
(resolve-gap/push gap local tzid orig) → moment?
  gap : tzgap?
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

Returns a moment where the local datetime portion is pushed forward by the length of the gap.

16.1.3 Overlap Resolvers

value
overlap-resolver/c : chaperone-contract?

A contract for overlap resolver functions. The contract is specified as:

(-> tzoverlap?
    datetime?
    string?
    (or/c moment? #f)
    moment?)

procedure
(resolve-overlap/pre overlap local tzid orig) → moment?
  overlap : tzoverlap?
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

Returns a moment for the given local datetime, using the UTC offset in effect before the overlap.

procedure
(resolve-overlap/post overlap
local
tzid
orig) → moment?
  overlap : tzoverlap?
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

Returns a moment for the given local datetime, using the UTC offset in effect after the overlap.

procedure
(resolve-overlap/retain overlap
local
tzid
orig) → moment?
  overlap : tzoverlap?
  local : datetime?
  tzid : string?
  orig : (or/c moment? #f)

If orig is a moment and its UTC offset is one of the ones involved in the given overlap, then the result will use that offset. Otherwise, this function behaves the same as resolve-overlap/post.

top ← prev up next →

1	Time Scale
2	Dates
3	Time-of-Day
4	Combined Date and Time
5	Moments
6	Date and Time Periods
7	Generic Date Operations
8	Generic Time Operations
9	Generic Datetime Operations
10	Generic Moment Operations
11	Date Arithmetic
12	Time Arithmetic
13	Datetime Arithmetic
14	Current Date and Time
15	Formatting and Parsing
16	Time Zones and UTC Offsets
17	Calendar Query Functions
18	Exceptions