/Crystal 0.31

class Time::Location


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 as UTC) it is considered fixed.

A Location 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 ZONEINFO. See .load for details.

Fixed Offset

A fixed offset location is created using Time::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 as Time::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")

Defined in:


Constant Summary

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

Describes the Coordinated Universal Time (UTC).

The only time zone offset in this location is Zone::UTC.


Class Method Summary

Instance Method Summary

Constructor Detail

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

Creates a Location instance named name with fixed offset in seconds from UTC.

def self.load(name : String) : LocationSource

Loads the Location with the given name.

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" and empty string ("") return Location::UTC, and "Local" returns Location.local.

The implementation uses a list of system-specifc 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 variable ZONEINFO. 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.


# This tries to load the file `/usr/share/zoneinfo/Custom/Location`
ENV["ZONEINFO"] = "/usr/share/zoneinfo/"

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

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.

def self.load_local : LocationSource

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

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

  • "UTC" and empty string ("") return Location::UTC
  • Any other value (such as "Europe/Berlin") is tried to be resolved using Location.load.
  • If ENV["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.

Class Method Detail

def self.fixed(offset : Int32)Source

Creates a Location instance with fixed offset in seconds from UTC.

The formatted offset is used as name.

def self.localSource

Returns the Location representing the application's local time zone.

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

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.local=(local : Location)Source

Instance Method Detail

def ==(other : self)

Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.

def fixed? : BoolSource

Returns true if this location has a fixed offset.

def hash(hasher)

Description copied from class Reference

See Object#hash(hasher)

def inspect(io : IO) : NilSource

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)

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

def local? : BoolSource

Returns true if this location equals to Time::Location.local.

def lookup(time : Time) : ZoneSource

Returns the time zone offset observed at time.

def lookup(unix_seconds : Int) : ZoneSource

Returns the time zone offset observed at unix_seconds.

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

def name : StringSource

Returns the name of this location.

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

def to_s(io : IO) : NilSource

Prints #name to io.

def utc? : BoolSource

Returns true if this location equals to UTC.

def zones : Array(Zone)Source

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

© 2012–2019 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.