class Time::Location


Location represents a specific time zone.

It can be either a time zone from the IANA Time Zone database, a fixed offset, or UTC.

Creating a location from timezone data:

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

Initializing a Time instance with specified Location:

time =, 2, 15, 21, 1, 10, location: location)

Alternatively, you can switch the Location for any Time instance:

time.location.to_s # => "Europe/Berlin"
time ="Asia/Jerusalem"))
time.location.to_s # => "Asia/Jerusalem"

There are also a few special conversions:

time.to_utc   # ==
time.to_local # ==

Defined in:


Constant Summary

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

Describes the Coordinated Universal Time (UTC).


Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

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

Constructor methods inherited from class Reference

new new

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
, =~(other) =~, class class, dup dup, hash(hasher)
, inspect(io : IO)
, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ")
, to_s
to_s(io : IO)
, to_yaml(io : IO)
, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

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

Constructor Detail

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

Returns the Location with the given name.

This uses a list of paths to look for timezone data. Each path can either point to a directory or an uncompressed ZIP file. System-specific default paths are provided by the implementation.

The first timezone data matching the given name that is successfully loaded and parsed is returned. A custom lookup path can be set as environment variable ZONEINFO.

Special names:

This method caches files based on the modification time, so subsequent loads of the same location name will return the same instance of Location unless the timezone database has been updated in between.

Example: ZONEINFO=/path/to/ crystal eval 'pp Location.load("Custom/Location")'

[View source]
def self.load_local : Location #

Loads the local location described by the current application environment.

It consults the environment variable ENV["TZ"] to find the time zone to use.

  • "UTC" and empty string "" return Location::UTC
  • "Foo/Bar" tries to load the zoneinfo from known system locations - such as /usr/share/zoneinfo/Foo/Bar, /usr/share/lib/zoneinfo/Foo/Bar or /usr/lib/locale/TZ/Foo/Bar on unix-based operating systems. See Location.load for details.
  • If ENV["TZ"] is not set, the system's local timezone data will be used (/etc/localtime on unix-based systems).
  • If no time zone data could be found, Location::UTC is returned.

[View source]

Class Method Detail

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

Creates a Location instance named name with fixed offset.

[View source]
def self.fixed(offset : Int32) #

Creates a Location instance with fixed offset.

[View source]
def self.local #

Returns the location representing the local time zone.

The value is loaded on first access based on the current application environment (see .load_local for details).

[View source]
def self.local=(local : Location) #

Instance Method Detail

def ==(other : self) #

def fixed? : Bool #

Returns true if this location has a fixed offset.

[View source]
def hash(hasher) #

def inspect(io : IO) #

[View source]
def local? : Bool #

Returns true if this location equals to Location.local.

[View source]
def lookup(time : Time) : Zone #

Returns the time zone in use at time.

[View source]
def lookup(epoch : Int) : Zone #

Returns the time zone in use at epoch (time in seconds since UNIX epoch).

[View source]
def name : String #

[View source]
def name=(name : String) #

[View source]
def to_s(io : IO) #

[View source]
def utc? : Bool #

Returns true if this location equals to UTC.

[View source]
def zones : Array(Zone) #

[View source]
def zones=(zones : Array(Zone)) #

[View source]