Class: TZInfo::Timezone

Inherits:

Object

Object
TZInfo::Timezone

Includes:: Comparable

Defined in:: lib/tzinfo/timezone.rb

Overview

Timezone is the base class of all timezones. It provides a factory method get to access timezones by identifier. Once a specific Timezone has been retrieved, DateTimes, Times and timestamps can be converted between the UTC and the local time for the zone. For example:

tz = TZInfo::Timezone.get('America/New_York')
puts tz.utc_to_local(DateTime.new(2005,8,29,15,35,0)).to_s
puts tz.local_to_utc(Time.utc(2005,8,29,11,35,0)).to_s
puts tz.utc_to_local(1125315300).to_s

Each time conversion method returns an object of the same type it was passed.

The timezone information all comes from the tz database (see www.twinsun.com/tz/tz-link.htm)

Direct Known Subclasses

Constant Summary collapse

@@loaded_zones = Cache of loaded zones by identifier to avoid using require if a zone has already been loaded.

{}

Class Method Summary collapse

.all ⇒ Object

At the moment, returns the result of all_country_zones.
.all_country_zone_identifiers ⇒ Object

Returns all the zone identifiers defined for all Countries.
.all_country_zones ⇒ Object

Returns all the Timezones defined for all Countries.
.all_identifiers ⇒ Object

At the moment, returns the result of all_country_zone_identifiers.
.get(identifier) ⇒ Object

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

If identifier is nil calls super(), else calls get(identifier).
.us_zone_identifiers ⇒ Object

Returns all US zone identifiers.
.us_zones ⇒ Object

Returns all US Timezone instances.

Instance Method Summary collapse

#<=>(tz) ⇒ Object

Compare two Timezones based on their identifier.
#==(tz) ⇒ Object

Two Timezones are considered to be equal if their identifiers are the same.
#current_period ⇒ Object

Returns the TimezonePeriod for the current time.
#current_period_and_time ⇒ Object (also: #current_time_and_period)

Returns the current Time and TimezonePeriod as an array.
#friendly_identifier(skip_first_part = false) ⇒ Object

Returns a friendlier version of the idenfitifer.
#identifier ⇒ Object

The identifier of the timezone, e.g.
#local_to_utc(local, dst = nil) ⇒ Object

Converts a time in the local timezone to UTC.
#name ⇒ Object

An alias for identifier.
#now ⇒ Object

Returns the current time in the timezone as a Time.
#period_for_local(local, dst = nil) ⇒ Object

Returns the TimezonePeriod for the given local time.
#period_for_utc(utc) ⇒ Object

Returns the TimezonePeriod for the given UTC time.
#periods ⇒ Object

:nodoc:.
#to_s ⇒ Object

Returns a friendlier version of the idenfitifer.
#utc_to_local(utc) ⇒ Object

Converts a time in UTC to the local timezone.

Class Method Details

.all ⇒ `Object`

At the moment, returns the result of all_country_zones. May be changed in the future to return all the Timezone instances including non-country specific zones.



108
109
110

# File 'lib/tzinfo/timezone.rb', line 108

def self.all
  all_country_zones
end

.all_country_zone_identifiers ⇒ `Object`

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 135

def self.all_country_zone_identifiers
  Country.all_codes.inject([]) {|zones,country|
    zones += Country.get(country).zone_identifiers
  }
end

.all_country_zones ⇒ `Object`

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 125

def self.all_country_zones
  Country.all_codes.inject([]) {|zones,country|
    zones += Country.get(country).zones
  }
end

.all_identifiers ⇒ `Object`

At the moment, returns the result of all_country_zone_identifiers. May be changed in the future to return all the zone identifiers including non-country specific zones.



115
116
117

# File 'lib/tzinfo/timezone.rb', line 115

def self.all_identifiers
  all_country_zone_identifiers
end

.get(identifier) ⇒ `Object`

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

Raises an exception of the timezone couldn’t be found.

# File 'lib/tzinfo/timezone.rb', line 73

def self.get(identifier)
  instance = @@loaded_zones[identifier]
  if instance.nil?      
    raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-z0-9\+\-_]+(\/[A-z0-9\+\-_]+)*$/
    identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__')
    begin
      require "tzinfo/definitions/#{identifier}"
      
      m = Definitions
      identifier.split(/\//).each {|part|
        m = m.const_get(part)
      }
      instance = m.instance
      @@loaded_zones[instance.identifier] = instance         
    rescue LoadError, NameError => e
      raise InvalidTimezoneIdentifier, e.message
    end
  end
  
  instance
end

.new(identifier = nil) ⇒ `Object`

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

# File 'lib/tzinfo/timezone.rb', line 97

def self.new(identifier = nil)
  if identifier        
    get(identifier)
  else
    super()
  end
end

.us_zone_identifiers ⇒ `Object`

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



152
153
154

# File 'lib/tzinfo/timezone.rb', line 152

def self.us_zone_identifiers
  Country.get('US').zone_identifiers
end

.us_zones ⇒ `Object`

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.



146
147
148

# File 'lib/tzinfo/timezone.rb', line 146

def self.us_zones
  Country.get('US').zones
end

Instance Method Details

#<=>(tz) ⇒ `Object`

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



370
371
372

# File 'lib/tzinfo/timezone.rb', line 370

def <=>(tz)
  identifier <=> tz.identifier
end

#==(tz) ⇒ `Object`

Two Timezones are considered to be equal if their identifiers are the same.



364
365
366

# File 'lib/tzinfo/timezone.rb', line 364

def ==(tz)
  identifier == tz.identifier
end

#current_period ⇒ `Object`

Returns the TimezonePeriod for the current time.



349
350
351

# File 'lib/tzinfo/timezone.rb', line 349

def current_period
  period_for_utc(Time.now.utc)
end

#current_period_and_time ⇒ `Object` Also known as: current_time_and_period

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 355

def current_period_and_time
  utc = Time.now.utc
  period = period_for_utc(utc)
  [period.to_local(utc), period]
end

#friendly_identifier(skip_first_part = false) ⇒ `Object`

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

# File 'lib/tzinfo/timezone.rb', line 175

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

#identifier ⇒ `Object`

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



157
158
159

# File 'lib/tzinfo/timezone.rb', line 157

def identifier
  'Unknown'
end

#local_to_utc(local, dst = nil) ⇒ `Object`

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

In the second case (more than one equivalent UTC time), an AmbiguousTime exception will be thrown 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.

# File 'lib/tzinfo/timezone.rb', line 331

def local_to_utc(local, dst = nil)
  TimeOrDateTime.wrap(local) {|local|
    if block_given?
      period = period_for_local(local, dst) {|periods| yield periods }
    else
      period = period_for_local(local, dst)
    end
    
    period.to_utc(local)
  }
end

#name ⇒ `Object`

An alias for identifier.

# File 'lib/tzinfo/timezone.rb', line 162

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

#now ⇒ `Object`

Returns the current time in the timezone as a Time.



344
345
346

# File 'lib/tzinfo/timezone.rb', line 344

def now
  utc_to_local(Time.now.utc)
end

#period_for_local(local, dst = nil) ⇒ `Object`

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

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

In the second case (more than one equivalent UTC time), an AmbiguousTime exception will be thrown 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.

# File 'lib/tzinfo/timezone.rb', line 254

def period_for_local(local, dst = nil)            
  results = periods.periods_for_local(local)
  
  # by this point, results must contain at least one period
  if 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.nil? && results.size == 1
        results.first
      else          
        raise AmbiguousTime, "#{local} is an ambiguous local time."
      end
    end
  end      
end

#period_for_utc(utc) ⇒ `Object`

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

If no TimezonePeriod could be found, PeriodNotFound is raised.



216
217
218

# File 'lib/tzinfo/timezone.rb', line 216

def period_for_utc(utc)            
  periods.period_for_utc(utc)      
end

#periods ⇒ `Object`

:nodoc:

Raises:

(UnknownTimezone)

# File 'lib/tzinfo/timezone.rb', line 374

def periods #:nodoc:
  raise UnknownTimezone, 'An attempt was made to perform a conversion on ' + 
    'an unknown timezone (i.e. one created with TZInfo::Timezone.new(nil))'
end

#to_s ⇒ `Object`

Returns a friendlier version of the idenfitifer.



168
169
170

# File 'lib/tzinfo/timezone.rb', line 168

def to_s
  friendly_identifier
end

#utc_to_local(utc) ⇒ `Object`

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

# File 'lib/tzinfo/timezone.rb', line 292

def utc_to_local(utc)
  TimeOrDateTime.wrap(utc) {|utc|
    period_for_utc(utc).to_local(utc)
  }
end

Class: TZInfo::Timezone

Overview

Direct Known Subclasses

Constant Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.all ⇒ Object

.all_country_zone_identifiers ⇒ Object

.all_country_zones ⇒ Object

.all_identifiers ⇒ Object

.get(identifier) ⇒ Object

.new(identifier = nil) ⇒ Object

.us_zone_identifiers ⇒ Object

.us_zones ⇒ Object

Instance Method Details

#<=>(tz) ⇒ Object

#==(tz) ⇒ Object

#current_period ⇒ Object

#current_period_and_time ⇒ Object Also known as: current_time_and_period

#friendly_identifier(skip_first_part = false) ⇒ Object

#identifier ⇒ Object

#local_to_utc(local, dst = nil) ⇒ Object

#name ⇒ Object

#now ⇒ Object

#period_for_local(local, dst = nil) ⇒ Object

#period_for_utc(utc) ⇒ Object

#periods ⇒ Object

#to_s ⇒ Object

#utc_to_local(utc) ⇒ Object