# class Time::Location

- Time::Location
- Reference
- Object

##
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 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`.

##
Constructors

- .fixed(name : String, offset : Int32) : Location

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

- .load(name : String) : Location

  Loads the `Location` with the given name.

- .load_local : Location

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

- .local : Location?

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

##
Class Method Summary

- .fixed(offset : Int32)

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

- .local=(local : Location)

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

##
Instance Method Summary

- #==(other : self)

  Returns `true` if other is equal to `self`.

- #fixed? : Bool

  Returns `true` if this location has a fixed offset.

- #hash(hasher)

  Returns `true` if other is equal to `self`.

- #inspect(io : IO) : Nil

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

- #local? : Bool

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

- #lookup(time : Time) : Zone

  Returns the time zone offset observed at time.

- #lookup(unix_seconds : Int) : Zone

  Returns the time zone offset observed at unix_seconds.

- #name : String

  Returns the name of this location.

- #to_s(io : IO) : Nil

  Prints `#name` to io.

- #utc? : Bool

  Returns `true` if this location equals to `UTC`.

- #zones : Array(Zone)

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

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, 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) same?, 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) ===, =~(other) =~, __crystal_pseudo_! : Bool __crystal_pseudo_!, __crystal_pseudo_as(type : Class) __crystal_pseudo_as, __crystal_pseudo_as?(type : Class) __crystal_pseudo_as?, __crystal_pseudo_is_a?(type : Class) : Bool __crystal_pseudo_is_a?, __crystal_pseudo_nil? : Bool __crystal_pseudo_nil?, __crystal_pseudo_responds_to?(name : Symbol) : Bool __crystal_pseudo_responds_to?, class class, dup dup, hash(hasher)
hash hash, inspect : String
inspect(io : IO) : Nil inspect, 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(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

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

##
Constructor Detail

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

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

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

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.

Example:

    # This tries to load the file `/usr/share/zoneinfo/Custom/Location`
    ENV["ZONEINFO"] = "/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["ZONEINFO"] = "/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.

def self.load_local : Location #

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.

def self.local : Location? #

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>

##
Class Method Detail

def self.fixed(offset : Int32) #

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

The formatted offset is used as name.

def self.local=(local : Location) #

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>

##
Instance Method Detail

def ==(other : self) #

Returns `true` if other is equal to `self`.

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

def fixed? : Bool #

Returns `true` if this location has a fixed offset.

def hash(hasher) #

Returns `true` if other is equal to `self`.

Two `Location` 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 #

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

def lookup(time : Time) : Zone #

Returns the time zone offset observed at time.

def lookup(unix_seconds : Int) : Zone #

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 : String #

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) : Nil #

Prints `#name` to io.

def utc? : Bool #

Returns `true` if this location equals to `UTC`.

def zones : Array(Zone) #

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