class Time::Location

Overview

Location maps time instants to the zone in use at that time. It typically represents the collection of time offsets observed in a certain geographical area.

It contains a list of zone offsets and rules for transitioning between them.

If a location has only one offset (such asUTC) it is considered fixed.

ALocation instance is usually retrieved by name using Time::Location.load. It loads the zone offsets and transitioning rules from the time zone database provided by the operating system.

location = Time::Location.load("Europe/Berlin")
location # => #<Time::Location Europe/Berlin>
time = Time.local(2016, 2, 15, 21, 1, 10, location: location)
time # => 2016-02-15 21:01:10+01:00[Europe/Berlin]

A custom time zone database can be configured through the environment variable TZDIR. See.load for details.

Fixed Offset

A fixed offset location is created usingTime::Location.fixed:

location = Time::Location.fixed(3600)
location       # => #<Time::Location +01:00>
location.zones # => [#<Time::Location::Zone +01:00 (0s) STD>]

Local Time Zone

The local time zone can be accessed asTime::Location.local.

It is initially configured according to system environment settings, but its value can be changed:

location = Time::Location.local
Time::Location.local = Time::Location.load("America/New_York")

Direct Known Subclasses

Defined in:

json/to_json.cr
time/location.cr
time/location/loader.cr
yaml/to_yaml.cr

Constant Summary

UTC = new("UTC", [Zone::UTC])

Describes the Coordinated Universal Time (UTC).

The only time zone offset in this location isZone::UTC.

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

Class methods inherited from class Reference

pre_initialize(address : Pointer) pre_initialize

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.fixed(name : String, offset : Int32) : Location #

Creates aLocation instance namedname with fixedoffset in seconds from UTC.


def self.fixed(offset : Int32) : self #

Creates aLocation instance with fixedoffset in seconds from UTC.

The formattedoffset is used as name.


def self.load(name : String) : Location #

Loads theLocation with the givenname.

location = Time::Location.load("Europe/Berlin")

name is understood to be a location name in the IANA Time Zone database, such as"America/New_York". As special cases, "UTC","Etc/UTC" and empty string ("") returnLocation::UTC, and "Local" returnsLocation.local.

The implementation uses a list of system-specific paths to look for a time zone database. The first time zone database entry matching the given name that is successfully loaded and parsed is returned. Typical paths on Unix-based operating systems are/usr/share/zoneinfo/, /usr/share/lib/zoneinfo/, or/usr/lib/locale/TZ/.

A time zone database may not be present on all systems, especially non-Unix systems. In this case, you may need to distribute a copy of the database with an application that depends on time zone data being available.

A custom lookup path can be set as environment variableTZDIR(ZONEINFO is also supported as legacy option). The path can point to the root of a directory structure or an uncompressed ZIP file, each representing the time zone database using files and folders of the expected names.

Example:

# This tries to load the file `/usr/share/zoneinfo/Custom/Location`
ENV["TZDIR"] = "/usr/share/zoneinfo/"
Time::Location.load("Custom/Location")

# This tries to load the file `Custom/Location` in the uncompressed ZIP
# file at `/path/to/zoneinfo.zip`
ENV["TZDIR"] = "/path/to/zoneinfo.zip"
Time::Location.load("Custom/Location")

If the location name cannot be found,InvalidLocationNameError is raised. If the loader encounters a format error in the time zone database, InvalidTZDataError is raised.

Files are cached based on the modification time, so subsequent request for the same location name will most likely return the same instance of Location, unless the time zone database has been updated in between.

  • .load? returnsnil if the location is unavailable.

def self.load_local : Location #

Loads the local time zone according to the current application environment.

The environment variableENV["TZ"] is consulted for finding the time zone to use.

  • "UTC","Etc/UTC" and empty string ("") returnLocation::UTC.
  • POSIX TZ strings (such as"EST5EDT,M3.2.0,M11.1.0") are parsed using Location.posix_tz.
  • Values beginning with a colon are implementation-defined according to POSIX, and not supported in Crystal.
  • Any other value (such as"Europe/Berlin") is tried to be resolved using Location.load.
  • IfENV["TZ"] is not set, the system's local time zone data will be used (/etc/localtime on unix-based systems).
  • If no time zone data could be found (i.e. the previous methods failed), Location::UTC is returned.

def self.local : Location #

Returns theLocation representing the application's local time zone.

Time uses this property as default value for most method arguments expecting aLocation.

The initial value depends on the current application environment, see .load_local for details.

The value can be changed to overwrite the system default:

Time.local.location # => #<Time::Location America/New_York>
Time::Location.local = Time::Location.load("Europe/Berlin")
Time.local.location # => #<Time::Location Europe/Berlin>

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) #

def self.new(pull : JSON::PullParser) #

Class Method Detail

def self.from_json_object_key?(key : String) : Time::Location #

def self.load?(name : String) : Location | Nil #

Loads theLocation with the givenname.

location = Time::Location.load("Europe/Berlin")

name is understood to be a location name in the IANA Time Zone database, such as"America/New_York". As special cases, "UTC","Etc/UTC" and empty string ("") returnLocation::UTC, and "Local" returnsLocation.local.

The implementation uses a list of system-specific paths to look for a time zone database. The first time zone database entry matching the given name that is successfully loaded and parsed is returned. Typical paths on Unix-based operating systems are/usr/share/zoneinfo/, /usr/share/lib/zoneinfo/, or/usr/lib/locale/TZ/.

A time zone database may not be present on all systems, especially non-Unix systems. In this case, you may need to distribute a copy of the database with an application that depends on time zone data being available.

A custom lookup path can be set as environment variableTZDIR(ZONEINFO is also supported as legacy option). The path can point to the root of a directory structure or an uncompressed ZIP file, each representing the time zone database using files and folders of the expected names.

Example:

# This tries to load the file `/usr/share/zoneinfo/Custom/Location`
ENV["TZDIR"] = "/usr/share/zoneinfo/"
Time::Location.load("Custom/Location")

# This tries to load the file `Custom/Location` in the uncompressed ZIP
# file at `/path/to/zoneinfo.zip`
ENV["TZDIR"] = "/path/to/zoneinfo.zip"
Time::Location.load("Custom/Location")

If the location name cannot be found,InvalidLocationNameError is raised. If the loader encounters a format error in the time zone database, InvalidTZDataError is raised.

Files are cached based on the modification time, so subsequent request for the same location name will most likely return the same instance of Location, unless the time zone database has been updated in between.

  • .load? returnsnil if the location is unavailable.

Returnsnil if the location is unavailable. RaisesInvalidLocationNameError if the name is invalid. RaisesInvalidTZDataError if the loader encounters a format error in the time zone database.

  • .load raises if the location is unavailable.

def self.local=(local : Location) #

Returns theLocation representing the application's local time zone.

Time uses this property as default value for most method arguments expecting aLocation.

The initial value depends on the current application environment, see .load_local for details.

The value can be changed to overwrite the system default:

Time.local.location # => #<Time::Location America/New_York>
Time::Location.local = Time::Location.load("Europe/Berlin")
Time.local.location # => #<Time::Location Europe/Berlin>

def self.posix_tz(name : String, str : String) : TZLocation #

Creates aLocation instance namedname with the given POSIX TZ string str, as defined inPOSIX.1-2024 Section 8.3.

str must begin with a standard time designator followed by a time offset; implementation-defined TZ strings beginning with a colon, as well as names from the time zone database, are not supported.

Ifstr designates a daylight saving time, then the transition times must also be present. A TZ string like"PST8PDT" alone is considered invalid, since no default transition rules are assumed.

location = Time::Location.posix_tz("America/New_York", "EST5EDT,M3.2.0,M11.1.0")
Time.utc(2025, 3, 9, 6).in(location)  # => 2025-03-09 01:00:00.0 -05:00 America/New_York
Time.utc(2025, 3, 9, 7).in(location)  # => 2025-03-09 03:00:00.0 -04:00 America/New_York
Time.utc(2025, 11, 2, 5).in(location) # => 2025-11-02 01:00:00.0 -04:00 America/New_York
Time.utc(2025, 11, 2, 6).in(location) # => 2025-11-02 01:00:00.0 -05:00 America/New_York

Instance Method Detail

def ==(other : self) #

Returnstrue ifother is equal toself.

TwoLocation instances are considered equal if they have the same name, offset zones and transition rules.


def fixed? : Bool #

Returnstrue if this location has a fixed offset.

Locations returned byLocation.posix_tz have a fixed offset if the TZ string specifies either no daylight saving time at all, or an all-year daylight saving time (e.g."EST5EDT,0/0,J365/25").


def hash(hasher) #

Returnstrue ifother is equal toself.

TwoLocation instances are considered equal if they have the same name, offset zones and transition rules.


def inspect(io : IO) : Nil #
Description copied from class Reference

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

def local? : Bool #

Returnstrue if this location equals toTime::Location.local.


def lookup(time : Time) : Zone #

Returns the time zone offset observed attime.


def lookup(unix_seconds : Int) : Zone #

Returns the time zone offset observed atunix_seconds.

unix_seconds expresses the number of seconds since UNIX epoch (1970-01-01 00:00:00Z).


def name : String #

Returns the name of this location.

It usually consists of a continent and city name separated by a slash, for exampleEurope/Berlin.


def to_json(json : JSON::Builder) : Nil #

def to_s(io : IO) : Nil #

Prints#name toio.


def to_yaml(yaml : YAML::Nodes::Builder) : Nil #

def utc? : Bool #

Returnstrue if this location equals toUTC.


def zones : Array(Zone) #

Returns the array of time zone offsets (Zone) used in this time zone.