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 as UTC
) it is considerd
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.new(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:
time/location/loader.crtime/location.cr
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.
Class Method Summary
-
.fixed(offset : Int32)
Creates a
Location
instance with fixed offset in seconds from UTC. -
.local
Returns the
Location
representing the application's local time zone. - .local=(local : Location)
Instance Method Summary
- #==(other : self)
-
#fixed? : Bool
Returns
true
if this location has a fixed offset. - #hash(hasher)
- #inspect(io : IO)
-
#local? : Bool
Returns
true
if this location equals toTime::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)
Prints
#name
to io. -
#utc? : Bool
Returns
true
if this location equals toUTC
. -
#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) =~, class class, dup dup, hash(hasher)
hash hash, inspect(io : IO)
inspect 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(&block) 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
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, 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) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io : String | IO) : self from_yaml
Constructor Detail
Creates a Location
instance named name with fixed offset in seconds
from UTC.
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.
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 (""
) returnLocation::UTC
- Any other value (such as
"Europe/Berlin"
) is tried to be resolved usingLocation.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
Creates a Location
instance with fixed offset in seconds from UTC.
The formatted offset is used as name.
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.now.location # => #<Time::Location America/New_York>
Time::Location.local = Time::Location.load("Europe/Berlin")
Time.now.location # => #<Time::Location Europe/Berlin>
Instance Method Detail
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
).
Returns the name of this location.
It usually consists of a continent and city name separated by a slash, for
example Europe/Berlin
.
Returns the array of time zone offsets (Zone
) used in this time zone.