class TZInfo::Timezone

# File lib/tzinfo/timezone.rb, line 516
def self._load(data)
  Timezone.get(data)
end

Loads a marshalled Timezone.

# File lib/tzinfo/timezone.rb, line 155
def self.all
  get_proxies(all_identifiers)
end

Returns an array containing all the available Timezones.

Returns TimezoneProxy objects to avoid the overhead of loading Timezone definitions until a conversion is actually required.

# File lib/tzinfo/timezone.rb, line 214
def self.all_country_zone_identifiers
  Country.all_codes.inject([]) {|zones,country|
    zones += Country.get(country).zone_identifiers
  }
end

Returns all the zone identifiers defined for all Countries. This is not the complete set of zone identifiers as some are not country specific (e.g. ‘Etc/GMT’). You can obtain a Timezone instance for a given identifier with the get method.

# File lib/tzinfo/timezone.rb, line 204
def self.all_country_zones
  Country.all_codes.inject([]) {|zones,country|
    zones += Country.get(country).zones
  }
end

Returns all the Timezones defined for all Countries. This is not the complete set of Timezones as some are not country specific (e.g. ‘Etc/GMT’).

Returns TimezoneProxy objects to avoid the overhead of loading Timezone definitions until a conversion is actually required.

# File lib/tzinfo/timezone.rb, line 177
def self.all_data_zone_identifiers
  load_index
  Indexes::Timezones.data_timezones
end

Returns an array containing the identifiers of all the available Timezones that are based on data (are not links to other Timezones)..

# File lib/tzinfo/timezone.rb, line 171
def self.all_data_zones
  get_proxies(all_data_zone_identifiers)
end

Returns an array containing all the available Timezones that are based on data (are not links to other Timezones).

Returns TimezoneProxy objects to avoid the overhead of loading Timezone definitions until a conversion is actually required.

# File lib/tzinfo/timezone.rb, line 161
def self.all_identifiers
  load_index
  Indexes::Timezones.timezones
end

Returns an array containing the identifiers of all the available Timezones.

# File lib/tzinfo/timezone.rb, line 193
def self.all_linked_zone_identifiers
  load_index
  Indexes::Timezones.linked_timezones
end

Returns an array containing the identifiers of all the available Timezones that are links to other Timezones.

# File lib/tzinfo/timezone.rb, line 187
def self.all_linked_zones
  get_proxies(all_linked_zone_identifiers)      
end

Returns an array containing all the available Timezones that are links to other Timezones.

Returns TimezoneProxy objects to avoid the overhead of loading Timezone definitions until a conversion is actually required.

# File lib/tzinfo/timezone.rb, line 87
def self.default_dst
  @@default_dst
end

Gets the default value of the optional dst parameter of the local_to_utc and period_for_local methods. Can be set to nil, true or false.

# File lib/tzinfo/timezone.rb, line 80
def self.default_dst=(value)
  @@default_dst = value.nil? ? nil : !!value
end

Sets the default value of the optional dst parameter of the local_to_utc and period_for_local methods. Can be set to nil, true or false.

The value of default_dst defaults to nil if unset.

# File lib/tzinfo/timezone.rb, line 95
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

Returns a timezone by its identifier (e.g. “Europe/London”, “America/Chicago” or “UTC”).

Raises InvalidTimezoneIdentifier if the timezone couldn’t be found.

# File lib/tzinfo/timezone.rb, line 531
def self.get_proxies(identifiers)
  identifiers.collect {|identifier| get_proxy(identifier)}
end

Returns an array of proxies corresponding to the given array of identifiers.

# File lib/tzinfo/timezone.rb, line 137
def self.get_proxy(identifier)
  TimezoneProxy.new(identifier)
end

Returns a proxy for the Timezone with the given identifier. The proxy will cause the real timezone to be loaded when an attempt is made to find a period or convert a time. get_proxy will not validate the identifier. If an invalid identifier is specified, no exception will be raised until the proxy is used.

# File lib/tzinfo/timezone.rb, line 522
def self.load_index
  unless @@index_loaded
    require 'tzinfo/indexes/timezones'
    @@index_loaded = true
  end        
end

Loads in the index of timezones if it hasn’t already been loaded.

# File lib/tzinfo/timezone.rb, line 143
def self.new(identifier = nil)
  if identifier        
    get(identifier)
  else
    super()
  end
end

If identifier is nil calls super(), otherwise calls get. An identfier should always be passed in when called externally.

# File lib/tzinfo/timezone.rb, line 231
def self.us_zone_identifiers
  Country.get('US').zone_identifiers
end

Returns all US zone identifiers. A shortcut for TZInfo::Country.get(‘US’).zone_identifiers.

# File lib/tzinfo/timezone.rb, line 225
def self.us_zones
  Country.get('US').zones
end

Returns all US Timezone instances. A shortcut for TZInfo::Country.get(‘US’).zones.

Returns TimezoneProxy objects to avoid the overhead of loading Timezone definitions until a conversion is actually required.

# File lib/tzinfo/timezone.rb, line 495
def <=>(tz)
  identifier <=> tz.identifier
end

Compares two Timezones based on their identifier. Returns -1 if tz is less than self, 0 if tz is equal to self and +1 if tz is greater than self.

# File lib/tzinfo/timezone.rb, line 511
def _dump(limit)
  identifier
end

Dumps this Timezone for marshalling.

# File lib/tzinfo/timezone.rb, line 457
def current_period
  period_for_utc(Time.now.utc)
end

Returns the TimezonePeriod for the current time.

# File lib/tzinfo/timezone.rb, line 463
def current_period_and_time
  utc = Time.now.utc
  period = period_for_utc(utc)
  [period.to_local(utc), period]
end

Returns the current Time and TimezonePeriod as an array. The first element is the time, the second element is the period.

# File lib/tzinfo/timezone.rb, line 501
def eql?(tz)
  self == tz
end

Returns true if and only if the identifier of tz is equal to the identifier of this Timezone.

# File lib/tzinfo/timezone.rb, line 266
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

Returns a friendlier version of the identifier. Set skip_first_part to omit the first part of the identifier (typically a region name) where there is more than one part.

For example:

Timezone.get('Europe/Paris').friendly_identifier(false)          #=> "Europe - Paris"
Timezone.get('Europe/Paris').friendly_identifier(true)           #=> "Paris"
Timezone.get('America/Indiana/Knox').friendly_identifier(false)  #=> "America - Knox, Indiana"
Timezone.get('America/Indiana/Knox').friendly_identifier(true)   #=> "Knox, Indiana"

# File lib/tzinfo/timezone.rb, line 506
def hash
  identifier.hash
end

Returns a hash of this Timezone.

# File lib/tzinfo/timezone.rb, line 236
def identifier
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
end

The identifier of the timezone, e.g. “Europe/Paris”.

# File lib/tzinfo/timezone.rb, line 252
def inspect
  "#<#{self.class}: #{identifier}>"
end

Returns internal object state as a programmer-readable string.

# File lib/tzinfo/timezone.rb, line 439
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

Converts a time in the local timezone to UTC. local can either be a DateTime, Time or timestamp (Time.to_i). The returned time has the same type as local. Any timezone information in local is ignored (it is treated as a local time).

Warning: There are local times that have no equivalent UTC times (e.g. in the transition from standard time to daylight savings time). There are also local times that have more than one UTC equivalent (e.g. in the transition from daylight savings time to standard time).

In the first case (no equivalent UTC time), a PeriodNotFound exception will be raised.

In the second case (more than one equivalent UTC time), an AmbiguousTime exception will be raised unless the optional dst parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the dst parameter can be used to select whether the daylight savings time or local time is used. For example,

Timezone.get('America/New_York').local_to_utc(DateTime.new(2004,10,31,1,30,0))

would raise an AmbiguousTime exception.

Specifying dst=true would return 2004-10-31 5:30:00. Specifying dst=false would return 2004-10-31 6:30:00.

If the dst parameter does not resolve the ambiguity, and a block is specified, it is called. The block must take a single parameter - an array of the periods that need to be resolved. The block can return a single period to use to convert the time or return nil or an empty array to cause an AmbiguousTime exception to be raised.

The default value of the dst parameter can be specified by setting Timezone.default_dst. If default_dst is not set, or is set to nil, then an AmbiguousTime exception will be raised in ambiguous situations unless a block is given to resolve the ambiguity.

# File lib/tzinfo/timezone.rb, line 241
def name
  # Don't use alias, as identifier gets overridden.
  identifier
end

An alias for identifier.

# File lib/tzinfo/timezone.rb, line 452
def now
  utc_to_local(Time.now.utc)
end

Returns the current time in the timezone as a Time.

# File lib/tzinfo/timezone.rb, line 356
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

Returns the TimezonePeriod for the given local time. local can either be a DateTime, Time or integer timestamp (Time.to_i). Any timezone information in local is ignored (it is treated as a time in the current timezone).

Warning: There are local times that have no equivalent UTC times (e.g. in the transition from standard time to daylight savings time). There are also local times that have more than one UTC equivalent (e.g. in the transition from daylight savings time to standard time).

In the first case (no equivalent UTC time), a PeriodNotFound exception will be raised.

In the second case (more than one equivalent UTC time), an AmbiguousTime exception will be raised unless the optional dst parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the dst parameter can be used to select whether the daylight savings time or local time is used. For example,

Timezone.get('America/New_York').period_for_local(DateTime.new(2004,10,31,1,30,0))

would raise an AmbiguousTime exception.

Specifying dst=true would the daylight savings period from April to October 2004. Specifying dst=false would return the standard period from October 2004 to April 2005.

If the dst parameter does not resolve the ambiguity, and a block is specified, it is called. The block must take a single parameter - an array of the periods that need to be resolved. The block can select and return a single period or return nil or an empty array to cause an AmbiguousTime exception to be raised.

The default value of the dst parameter can be specified by setting Timezone.default_dst. If default_dst is not set, or is set to nil, then an AmbiguousTime exception will be raised in ambiguous situations unless a block is given to resolve the ambiguity.

# File lib/tzinfo/timezone.rb, line 305
def period_for_utc(utc)            
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'      
end

Returns the TimezonePeriod for the given UTC time. utc can either be a DateTime, Time or integer timestamp (Time.to_i). Any timezone information in utc is ignored (it is treated as a UTC time).

# File lib/tzinfo/timezone.rb, line 313
def periods_for_local(local)
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
end

Returns the set of TimezonePeriod instances that are valid for the given local time as an array. If you just want a single period, use period_for_local instead and specify how ambiguities should be resolved. Returns an empty array if no periods are found for the given time.

# File lib/tzinfo/timezone.rb, line 475
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

Converts a time in UTC to local time and returns it as a string according to the given format. The formatting is identical to Time.strftime and DateTime.strftime, except %Z is replaced with the timezone abbreviation for the specified time (for example, EST or EDT).

# File lib/tzinfo/timezone.rb, line 247
def to_s
  friendly_identifier
end

Returns a friendlier version of the identifier.

# File lib/tzinfo/timezone.rb, line 395
def utc_to_local(utc)
  TimeOrDateTime.wrap(utc) {|wrapped|
    period_for_utc(wrapped).to_local(wrapped)
  }
end

Converts a time in UTC to the local timezone. utc can either be a DateTime, Time or timestamp (Time.to_i). The returned time has the same type as utc. Any timezone information in utc is ignored (it is treated as a UTC time).