▼Gregor:   Dates and Times
►16 Time Zones and UTC Offsets
On this page:
tz/  c
current-timezone
16.1 Resolving UTC Offsets
16.1.1 Offset Resolvers
offset-resolver/  c
offset-resolver
resolve-offset/  raise
resolve-offset/  pre
resolve-offset/  post
resolve-offset/  post-gap/  pre-overlap
resolve-offset/  retain
resolve-offset/  push
16.1.2 Gap Resolvers
gap-resolver/  c
resolve-gap/  pre
resolve-gap/  post
resolve-gap/  push
16.1.3 Overlap Resolvers
overlap-resolver/  c
resolve-overlap/  pre
resolve-overlap/  post
resolve-overlap/  retain
7.7
  top  ← prev  up  next → 

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 →