class TZInfo::Timezone
(see www.twinsun.com/tz/tz-link.htm)
The timezone information all comes from the tz database
passed.
Each time conversion method returns an object of the same type it was
puts tz.utc_to_local(1125315300).to_s
puts tz.local_to_utc(Time.utc(2005,8,29,11,35,0)).to_s
puts tz.utc_to_local(DateTime.new(2005,8,29,15,35,0)).to_s
tz = TZInfo::Timezone.get(‘America/New_York’)
and the local time for the zone. For example:
retrieved, DateTimes, Times and timestamps can be converted between the UTC
get to access timezones by identifier. Once a specific Timezone has been
Timezone is the base class of all timezones. It provides a factory method
def self._load(data)
def self._load(data) Timezone.get(data) end
def self.all
Returns TimezoneProxy objects to avoid the overhead of loading Timezone
Returns an array containing all the available Timezones.
def self.all get_proxies(all_identifiers) end
def self.all_country_zone_identifiers
'Etc/GMT'). You can obtain a Timezone instance for a given identifier
complete set of zone identifiers as some are not country specific (e.g.
Returns all the zone identifiers defined for all Countries. This is not the
def self.all_country_zone_identifiers Country.all_codes.inject([]) {|zones,country| zones += Country.get(country).zone_identifiers } end
def self.all_country_zones
Returns TimezoneProxy objects to avoid the overhead of loading Timezone
'Etc/GMT').
complete set of Timezones as some are not country specific (e.g.
Returns all the Timezones defined for all Countries. This is not the
def self.all_country_zones Country.all_codes.inject([]) {|zones,country| zones += Country.get(country).zones } end
def self.all_data_zone_identifiers
Returns an array containing the identifiers of all the available
def self.all_data_zone_identifiers load_index Indexes::Timezones.data_timezones end
def self.all_data_zones
Returns TimezoneProxy objects to avoid the overhead of loading Timezone
on data (are not links to other Timezones).
Returns an array containing all the available Timezones that are based
def self.all_data_zones get_proxies(all_data_zone_identifiers) end
def self.all_identifiers
Returns an array containing the identifiers of all the available
def self.all_identifiers load_index Indexes::Timezones.timezones end
def self.all_linked_zone_identifiers
Returns an array containing the identifiers of all the available
def self.all_linked_zone_identifiers load_index Indexes::Timezones.linked_timezones end
def self.all_linked_zones
Returns TimezoneProxy objects to avoid the overhead of loading Timezone
to other Timezones.
Returns an array containing all the available Timezones that are links
def self.all_linked_zones get_proxies(all_linked_zone_identifiers) end
def self.default_dst
local_to_utc and period_for_local methods. Can be set to nil, true or
Gets the default value of the optional dst parameter of the
def self.default_dst @@default_dst end
def self.default_dst=(value)
false.
local_to_utc and period_for_local methods. Can be set to nil, true or
Sets the default value of the optional dst parameter of the
def self.default_dst=(value) @@default_dst = value.nil? ? nil : !!value end
def self.get(identifier)
"America/Chicago" or "UTC").
Returns a timezone by its identifier (e.g. "Europe/London",
def self.get(identifier) instance = @@loaded_zones[identifier] unless instance raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-Za-z0-9\+\-_]+(\/[A-Za-z0-9\+\-_]+)*$/ identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__') begin # Use a temporary variable to avoid an rdoc warning file = "tzinfo/definitions/#{identifier}".untaint require file m = Definitions identifier.split(/\//).each {|part| m = m.const_get(part) } info = m.get # Could make Timezone subclasses register an interest in an info # type. Since there are currently only two however, there isn't # much point. if info.kind_of?(DataTimezoneInfo) instance = DataTimezone.new(info) elsif info.kind_of?(LinkedTimezoneInfo) instance = LinkedTimezone.new(info) else raise InvalidTimezoneIdentifier, "No handler for info type #{info.class}" end @@loaded_zones[instance.identifier] = instance rescue LoadError, NameError => e raise InvalidTimezoneIdentifier, e.message end end instance end
def self.get_proxies(identifiers)
Returns an array of proxies corresponding to the given array of
def self.get_proxies(identifiers) identifiers.collect {|identifier| get_proxy(identifier)} end
def self.get_proxy(identifier)
identifier. If an invalid identifier is specified, no exception will be
find a period or convert a time. get_proxy will not validate the
will cause the real timezone to be loaded when an attempt is made to
Returns a proxy for the Timezone with the given identifier. The proxy
def self.get_proxy(identifier) TimezoneProxy.new(identifier) end
def self.load_index
def self.load_index unless @@index_loaded require 'tzinfo/indexes/timezones' @@index_loaded = true end end
def self.new(identifier = nil)
If identifier is nil calls super(), otherwise calls get. An identfier
def self.new(identifier = nil) if identifier get(identifier) else super() end end
def self.us_zone_identifiers
Returns all US zone identifiers. A shortcut for
def self.us_zone_identifiers Country.get('US').zone_identifiers end
def self.us_zones
Returns TimezoneProxy objects to avoid the overhead of loading Timezone
TZInfo::Country.get('US').zones.
Returns all US Timezone instances. A shortcut for
def self.us_zones Country.get('US').zones end
def <=>(tz)
Compares two Timezones based on their identifier. Returns -1 if tz is less
def <=>(tz) identifier <=> tz.identifier end
def _dump(limit)
def _dump(limit) identifier end
def current_period
def current_period period_for_utc(Time.now.utc) end
def current_period_and_time
Returns the current Time and TimezonePeriod as an array. The first element
def current_period_and_time utc = Time.now.utc period = period_for_utc(utc) [period.to_local(utc), period] end
def eql?(tz)
Returns true if and only if the identifier of tz is equal to the
def eql?(tz) self == tz end
def friendly_identifier(skip_first_part = false)
Timezone.get('America/Indiana/Knox').friendly_identifier(false) #=> "America - Knox, Indiana"
Timezone.get('Europe/Paris').friendly_identifier(true) #=> "Paris"
Timezone.get('Europe/Paris').friendly_identifier(false) #=> "Europe - Paris"
For example:
there is more than one part.
omit the first part of the identifier (typically a region name) where
Returns a friendlier version of the identifier. Set skip_first_part to
def friendly_identifier(skip_first_part = false) parts = identifier.split('/') if parts.empty? # shouldn't happen identifier elsif parts.length == 1 parts[0] else if skip_first_part result = '' else result = parts[0] + ' - ' end parts[1, parts.length - 1].reverse_each {|part| part.gsub!(/_/, ' ') if part.index(/[a-z]/) # Missing a space if a lower case followed by an upper case and the # name isn't McXxxx. part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2') part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2') # Missing an apostrophe if two consecutive upper case characters. part.gsub!(/([A-Z])([A-Z])/, '\1\'\2') end result << part result << ', ' } result.slice!(result.length - 2, 2) result end end
def hash
def hash identifier.hash end
def identifier
def identifier raise UnknownTimezone, 'TZInfo::Timezone constructed directly' end
def inspect
def inspect "#<#{self.class}: #{identifier}>" end
def local_to_utc(local, dst = Timezone.default_dst)
an AmbiguousTime exception will be raised in ambiguous situations unless
Timezone.default_dst. If default_dst is not set, or is set to nil, then
The default value of the dst parameter can be specified by setting
to cause an AmbiguousTime exception to be raised.
single period to use to convert the time or return nil or an empty array
array of the periods that need to be resolved. The block can return a
specified, it is called. The block must take a single parameter - an
If the dst parameter does not resolve the ambiguity, and a block is
would return 2004-10-31 6:30:00.
Specifying dst=true would return 2004-10-31 5:30:00. Specifying dst=false
would raise an AmbiguousTime exception.
Timezone.get('America/New_York').local_to_utc(DateTime.new(2004,10,31,1,30,0))
daylight savings time or local time is used. For example,
standard time, the dst parameter can be used to select whether the
If the ambiguity is due to a transition from daylight savings time to
handles the ambiguity.
exception will be raised unless the optional dst parameter or block
In the second case (more than one equivalent UTC time), an AmbiguousTime
will be raised.
In the first case (no equivalent UTC time), a PeriodNotFound exception
transition from daylight savings time to standard time).
also local times that have more than one UTC equivalent (e.g. in the
in the transition from standard time to daylight savings time). There are
Warning: There are local times that have no equivalent UTC times (e.g.
as a local time).
type as local. Any timezone information in local is ignored (it is treated
a DateTime, Time or timestamp (Time.to_i). The returned time has the same
Converts a time in the local timezone to UTC. local can either be
def local_to_utc(local, dst = Timezone.default_dst) TimeOrDateTime.wrap(local) {|wrapped| if block_given? period = period_for_local(wrapped, dst) {|periods| yield periods } else period = period_for_local(wrapped, dst) end period.to_utc(wrapped) } end
def name
def name # Don't use alias, as identifier gets overridden. identifier end
def now
def now utc_to_local(Time.now.utc) end
def period_for_local(local, dst = Timezone.default_dst)
an AmbiguousTime exception will be raised in ambiguous situations unless
Timezone.default_dst. If default_dst is not set, or is set to nil, then
The default value of the dst parameter can be specified by setting
to cause an AmbiguousTime exception to be raised.
return a single period or return nil or an empty array
array of the periods that need to be resolved. The block can select and
specified, it is called. The block must take a single parameter - an
If the dst parameter does not resolve the ambiguity, and a block is
from October 2004 to April 2005.
October 2004. Specifying dst=false would return the standard period
Specifying dst=true would the daylight savings period from April to
would raise an AmbiguousTime exception.
Timezone.get('America/New_York').period_for_local(DateTime.new(2004,10,31,1,30,0))
daylight savings time or local time is used. For example,
standard time, the dst parameter can be used to select whether the
If the ambiguity is due to a transition from daylight savings time to
handles the ambiguity.
exception will be raised unless the optional dst parameter or block
In the second case (more than one equivalent UTC time), an AmbiguousTime
will be raised.
In the first case (no equivalent UTC time), a PeriodNotFound exception
transition from daylight savings time to standard time).
also local times that have more than one UTC equivalent (e.g. in the
in the transition from standard time to daylight savings time). There are
Warning: There are local times that have no equivalent UTC times (e.g.
timezone).
information in local is ignored (it is treated as a time in the current
a DateTime, Time or integer timestamp (Time.to_i). Any timezone
Returns the TimezonePeriod for the given local time. local can either be
def period_for_local(local, dst = Timezone.default_dst) results = periods_for_local(local) if results.empty? raise PeriodNotFound elsif results.size < 2 results.first else # ambiguous result try to resolve if !dst.nil? matches = results.find_all {|period| period.dst? == dst} results = matches if !matches.empty? end if results.size < 2 results.first else # still ambiguous, try the block if block_given? results = yield results end if results.is_a?(TimezonePeriod) results elsif results && results.size == 1 results.first else raise AmbiguousTime, "#{local} is an ambiguous local time." end end end end
def period_for_utc(utc)
a DateTime, Time or integer timestamp (Time.to_i). Any timezone
Returns the TimezonePeriod for the given UTC time. utc can either be
def period_for_utc(utc) raise UnknownTimezone, 'TZInfo::Timezone constructed directly' end
def periods_for_local(local)
period_for_local instead and specify how ambiguities should be resolved.
local time as an array. If you just want a single period, use
Returns the set of TimezonePeriod instances that are valid for the given
def periods_for_local(local) raise UnknownTimezone, 'TZInfo::Timezone constructed directly' end
def strftime(format, utc = Time.now.utc)
Time.strftime and DateTime.strftime, except %Z is replaced with the
according to the given format. The formatting is identical to
Converts a time in UTC to local time and returns it as a string
def strftime(format, utc = Time.now.utc) period = period_for_utc(utc) local = period.to_local(utc) local = Time.at(local).utc unless local.kind_of?(Time) || local.kind_of?(DateTime) abbreviation = period.abbreviation.to_s.gsub(/%/, '%%') format = format.gsub(/(.?)%Z/) do if $1 == '%' # return %%Z so the real strftime treats it as a literal %Z too '%%Z' else "#$1#{abbreviation}" end end local.strftime(format) end
def to_s
def to_s friendly_identifier end
def utc_to_local(utc)
type as utc. Any timezone information in utc is ignored (it is treated as
a DateTime, Time or timestamp (Time.to_i). The returned time has the same
Converts a time in UTC to the local timezone. utc can either be
def utc_to_local(utc) TimeOrDateTime.wrap(utc) {|wrapped| period_for_utc(wrapped).to_local(wrapped) } end