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)

Loads a marshalled Timezone.
def self._load(data)
  Timezone.get(data)
end

def self.all

definitions until a conversion is actually required.
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

with the get method.
'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

definitions until a conversion is actually required.
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

Timezones that are based on data (are not links to other Timezones)..
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

definitions until a conversion is actually required.
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

Timezones.
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

Timezones that are links to other Timezones.
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

definitions until a conversion is actually required.
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

false.
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)

The value of default_dst defaults to nil if unset.

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)

Raises InvalidTimezoneIdentifier if the timezone couldn't be found.

"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)

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)

raised until the proxy is used.
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

Loads in the index of timezones if it hasn't already been loaded.
def self.load_index
  unless @@index_loaded
    require 'tzinfo/indexes/timezones'
    @@index_loaded = true
  end        
end

def self.new(identifier = nil)

should always be passed in when called externally.
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

TZInfo::Country.get('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

definitions until a conversion is actually required.
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)

than self, 0 if tz is equal to self and +1 if tz is greater than self.
Compares two Timezones based on their identifier. Returns -1 if tz is less
def <=>(tz)
  identifier <=> tz.identifier
end

def _dump(limit)

Dumps this Timezone for marshalling.
def _dump(limit)
  identifier
end

def current_period

Returns the TimezonePeriod for the current time.
def current_period
  period_for_utc(Time.now.utc)
end

def current_period_and_time

is the time, the second element is the period.
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)

identifier of this Timezone.
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(true) #=> "Knox, Indiana"
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

Returns a hash of this Timezone.
def hash
  identifier.hash
end

def identifier

The identifier of the timezone, e.g. "Europe/Paris".
def identifier
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
end

def inspect

Returns internal object state as a programmer-readable string.
def inspect
  "#<#{self.class}: #{identifier}>"
end

def local_to_utc(local, dst = Timezone.default_dst)

a block is given to resolve the ambiguity.
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

An alias for identifier.
def name
  # Don't use alias, as identifier gets overridden.
  identifier
end

def now

Returns the current time in the timezone as a Time.
def now
  utc_to_local(Time.now.utc)
end

def period_for_local(local, dst = Timezone.default_dst)

a block is given to resolve the ambiguity.
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)

information in utc is ignored (it is treated as a UTC time).
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)

Returns an empty array if no periods are found for the given time.
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)

timezone abbreviation for the specified time (for example, EST or EDT).
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

Returns a friendlier version of the identifier.
def to_s
  friendly_identifier
end

def utc_to_local(utc)

a UTC time).
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