TZInfo

7.7

top ← prev up next →

TZInfo

package: tzinfo

1 Introduction

The tzinfo library provides an interface for querying the IANA time zone database (also known as the Olson database).

UNIX systems usually come with a compiled version of the IANA database (typically in /usr/share/zoneinfo). tzinfo will use the system’s database if available. However, if the tzdata package is installed, that will be used instead. Since Windows systems do not come with a zoneinfo database, tzdata will automatically be installed on Windows systems when tzinfo is installed.

2 Querying the Database

procedure
(all-tzids) → (listof string?)

Returns a list containing all of the time zone IDs in the database.

procedure
(tzid-exists? tzid) → boolean?
tzid : string?

Returns #t if the given ID is in the database, #f otherwise.

Examples:

> (tzid-exists? "Europe/London")
#t
> (tzid-exists? "Fillory/Whitespire")
#f

procedure
(utc-seconds->tzoffset tzid seconds) → tzoffset?
tzid : string?
seconds : real?

For a given time zone ID and number of seconds since the UNIX epoch (1970-01-01 00:00:00 UTC), returns a tzoffset? describing the offset from UTC in effect at that moment of time in the given time zone. Raises exn:fail:tzinfo:zone-not-found if the given time zone ID is not in the database.

Examples:

> (utc-seconds->tzoffset "America/New_York" 0)
(tzoffset -18000 #f "EST")
> (utc-seconds->tzoffset "Fillory/Whitespire" 0)
Cannot find zoneinfo file for [Fillory/Whitespire]

procedure
(local-seconds->tzoffset tzid seconds)
→ (or/c tzoffset? tzgap? tzoverlap?)
tzid : string?
seconds : real?

For a given time zone ID and number of seconds since 1970-01-01 00:00:00 in the given time zone, returns one of:

a tzoffset struct, describing the offset from UTC in effect at the given time in the given time zone;
a tzgap struct if the given local time falls into a gap between different offsets (as, for example, when an hour is skipped at the start of daylight saving time in most parts of the United States); or
a tzoverlap struct if the given local time falls in a period when two different offsets might be in effect (as, for example, at the end of daylight saving time, when an hour is repeated).

Raises exn:fail:tzinfo:zone-not-found if the given time zone ID is not in the database.

Examples:

> (local-seconds->tzoffset "America/New_York" 1409606993)
(tzoffset -14400 #t "EDT")
> (local-seconds->tzoffset "America/New_York" 1394330400)
(tzgap 1394348400 (tzoffset -18000 #f "EST") (tzoffset -14400 #t "EDT"))
> (local-seconds->tzoffset "America/New_York" 1414890000)
(tzoverlap (tzoffset -14400 #t "EDT") (tzoffset -18000 #f "EST"))

procedure
(tzid->country-codes tzid) → (listof string?)
tzid : string?

Returns a list of ISO 3166 alpha-2 country codes in which the given time zone is used.

Examples:

> (tzid->country-codes "Europe/Moscow")
'("RU")
> (tzid->country-codes "Antarctica/Troll")
'("AQ")
> (tzid->country-codes "Africa/Kinshasa")
'()

procedure
(country-code->tzids cc) → (listof string?)
cc : string?

Returns a list of time zone IDs that are used in the country identified by the given ISO 3166 alpha-2 country code.

Examples:

> (country-code->tzids "US")
'("America/Indiana/Indianapolis"
  "America/Detroit"
  "America/Nome"
  "America/Indiana/Vincennes"
  "America/Adak"
  "America/Sitka"
  "America/North_Dakota/New_Salem"
  "America/Indiana/Petersburg"
  "America/Los_Angeles"
  "America/Indiana/Winamac"
  "America/Indiana/Marengo"
  "America/New_York"
  "America/North_Dakota/Beulah"
  "America/Indiana/Knox"
  "America/Denver"
  "America/Phoenix"
  "America/Juneau"
  "America/Chicago"
  "America/North_Dakota/Center"
  "America/Boise"
  "America/Kentucky/Monticello"
  "America/Indiana/Tell_City"
  "Pacific/Honolulu"
  "America/Metlakatla"
  "America/Anchorage"
  "America/Indiana/Vevay"
  "America/Menominee"
  "America/Yakutat"
  "America/Kentucky/Louisville")
> (country-code->tzids "IT")
'("Europe/Rome")

procedure
(system-tzid) → (or/c string? #f)

Returns the ID of the current system time zone, if it can be determined, #f otherwise.

struct
(struct exn:fail:tzinfo:zone-not-found ())

An exception that is raised by query functions when the given time zone ID does not exist in the tzinfo database.

3 Offsets, Gaps, and Overlaps

struct
(struct tzoffset (utc-seconds dst? abbreviation)
    #:transparent)
  utc-seconds : exact-integer?
  dst? : boolean?
  abbreviation : string?

A structure type representing a time zone-specific offset from UTC. utc-seconds contains the different from UTC in seconds. dst? is true just in case the offset represents an offset in effect during daylight saving time. abbreviation is, e.g., "EST" for "Eastern Standard Time," "BST" for "British Summer Time," etc.

struct
(struct tzgap (starts-at offset-before offset-after)
    #:transparent)
  starts-at : exact-integer?
  offset-before : tzoffset?
  offset-after : tzoffset?

A structure type representing a time zone-specific gap between two offsets from UTC. Gaps occur at the start of daylight saving time. starts-at is the start of the gap, represented as a number of seconds since the UNIX epoch. offset-before is the tzoffset in effect before the gap. offset-after is the tzoffset in effect after the gap.

struct
(struct tzoverlap (offset-before offset-after)
    #:transparent)
  offset-before : tzoffset?
  offset-after : tzoffset?

A structure type representing a time-zone specific overlap of two different offsets. Overlaps occur at the end of daylight saving time. offset-before is the earlier offset. E.g., when going from daylight saving time to standard time, offset-before is the daylight saving time offset. offset-after is the later offset.

4 Data Sources

tzinfo allows for a pluggable data sources. At present, the only supported source is based on zoneinfo files, which are a compiled form of the IANA database, widely- used on UNIX systems.

parameter
(current-tzinfo-source) → tzinfo-source?
(current-tzinfo-source tzinfo-source) → void?
tzinfo-source : tzinfo-source?
= #f

A parameter containing the current tzinfo data source.

procedure
(set-default-tzinfo-source-constructor! ctor) → void?
ctor : (-> tzinfo-source?)

Sets the constructor function that will be applied to build the default tzinfo source. To use a custom source, you must call this function before using any of the querying functions.

struct
(struct exn:fail:tzinfo:zoneinfo-not-found ())

An exception that can be raised by any function that attempts to construct a zoneinfo-based data source, when the zoneinfo database cannot be found.

5 Data Source Generics

(require tzinfo/source)

package: tzinfo

value
gen:tzinfo-source : any/c

A generic interface for defining custom tzinfo data sources. It defines the following methods:

tzinfo->all-tzids
tzinfo-has-tzid?
tzinfo-tzid->country-codes
tzinfo-country-code->tzids
seconds->tzoffset/utc
seconds->tzoffset/local
detect-system-tzid

procedure
(tzinfo-source? v) → boolean?
v : any/c

Returns #t if v is a tzinfo source, #f otherwise.

procedure
(tzinfo->all-tzids src) → (listof string?)
src : tzinfo-source?

Returns the full list of time zone IDs contained in the given tzinfo source.

procedure
(tzinfo-has-tzid? src tzid) → boolean?
src : tzinfo-source?
tzid : string?

#t if the tzinfo source contains the given time zone ID, #f otherwise.

procedure
(tzinfo-tzid->country-codes src tzid) → (listof string?)
src : tzinfo-source?
tzid : string?

Returns the list of ISO 3166 alpha-2 country codes in which the given time zone is used, accoring to the tzinfo source data.

procedure
(tzinfo-country-code->tzids src cc) → (listof string?)
src : tzinfo-source?
cc : string?

Returns the list of time zone IDs that are used in the given country (identified by an ISO 3166 alpha-2 country code), according to the tzinfo data source.

procedure
(seconds->tzoffset/utc src tzid seconds) → tzoffset?
  src : tzinfo-source?
  tzid : string?
  seconds : real?

Returns the tzoffset in use at the given UTC time in the given time zone, according to the tzinfo source.

procedure
(seconds->tzoffset/local src tzid seconds)
→ (or/c tzoffset? tzgap? tzoverlap?)
  src : tzinfo-source?
  tzid : string?
  seconds : real?

Returns a tzoffset, tzgap, or tzoveralap, depending on what offset is in effect at the given local time in the given time zone, according to the tzinfo source.

procedure
(detect-system-tzid) → (or/c string? #f)

Returns the time zone ID currently in use by the operating system, if it can be detected, #f otherwise.

6 Building standalone executables that use tzinfo

If you build a standalone executable (with raco exe) that uses this library, you should keep in mind where you intend to deploy it. Most UNIX / MacOS systems come with the zoneinfo database installed, but Windows systems do not, nor do some minimal UNIX systems.

To ensure that the target system will be able to find and use zoneinfo files, wherever you deploy your executable, you should install the tzdata package. (When you install tzinfo on a Windows system, tzdata is automatically installed.) If tzdata is installed, the zoneinfo files will be bundled with your executable when you use raco distribute.

top ← prev up next →

1	Introduction
2	Querying the Database
3	Offsets, Gaps, and Overlaps
4	Data Sources
5	Data Source Generics
6	Building standalone executables that use tzinfo