Class: TZInfo::Timezone

Inherits:

Object

Object
TZInfo::Timezone

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 and Times 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

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

Direct Known Subclasses

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

#current_period ⇒ Object

Returns the TimezonePeriod for the current time.
#current_period_and_time ⇒ Object

Returns the current time and TimezonePeriod as an array.
#identifier ⇒ Object

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

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

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

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

Returns the TimezonePeriod for the given UTC time.
#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.



47
48
49

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

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 76

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

This method will take a substantial time to return the first time it is called as all the Timezone classes will have to be loaded by Ruby. If you just want the zone identifiers use all_country_zone_identifiers instead.

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

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.



54
55
56

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

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 23

def self.get(identifier)
  raise 'Invalid identifier' if identifier !~ /^[A-z0-9\+\-_]+(\/[A-z0-9\+\-_]+)*$/
  identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__')
  require "tzinfo/definitions/#{identifier}"
  
  m = Definitions
  identifier.split(/\//).each {|part|
    m = m.const_get(part)
  }
  m.instance      
end

.new(identifier = nil) ⇒ `Object`

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

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

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.



91
92
93

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

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. If you only need the zone identifiers, use us_zone_identifiers instead.



85
86
87

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

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

Instance Method Details

#current_period ⇒ `Object`

Returns the TimezonePeriod for the current time.



200
201
202

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

def current_period
  period_for_utc(Time.now.utc)
end

#current_period_and_time ⇒ `Object`

Returns the current time and TimezonePeriod as an array.

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

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

#identifier ⇒ `Object`

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



96
97
98

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

def identifier
  'Unknown'
end

#local_to_utc(local) ⇒ `Object`

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

During the period when daylight savings reverts to standard time and there are two possible UTC times for each local time, local_to_utc returns the earlier time.

For times skipped during a change to daylight savings, PeriodNotFound is raised.

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

def local_to_utc(local)
  run_on_datetime(local) {|local|      
    period_for_local(local).to_utc(local)
  }
end

#now ⇒ `Object`

Returns the current time in the timezone as a Time.



195
196
197

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

def now
  utc_to_local(Time.now.utc)
end

#period_for_local(local) ⇒ `Object`

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

If no TimezonePeriod could be found, PeriodNotFound is raised. This will happen when a change to daylight savings occurs and an hour is skipped.

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

def period_for_local(local)  
  run_on_datetime(local) {|local|
    # dumb search for now      
    periods.each {|period|
      if period.valid_for_local?(local)
        return period          
      end
    }
      
    # if nothing found, assume the first and last periods are unbounded
    if periods.length > 0
      
      last = periods[periods.length - 1] 
      if last.local_after_start?(local)
        last
      else
        first = periods[0]
        if first.local_before_end?(local)
          first
        else
          raise PeriodNotFound, "No time period found for #{utc}. This could be because a change to daylight savings time caused an hour to be skipped."
        end
      end
    else
      raise PeriodNotFound, "No time period found for #{utc}. This could be because a change to daylight savings time caused an hour to be skipped."
    end
  }
end

#period_for_utc(utc) ⇒ `Object`

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

If no TimezonePeriod could be found, PeriodNotFound is raised.

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

def period_for_utc(utc)
  run_on_datetime(utc) {|utc|
    # dumb search for now      
    periods.each {|period|
      if period.valid_for_utc?(utc)
        return period          
      end
    }
      
    # if nothing found, assume the first and last periods are unbounded
    if periods.length > 0
      
      last = periods[periods.length - 1] 
      if last.utc_after_start?(utc)
        last
      else
        first = periods[0]
        if first.utc_before_end?(utc)
          first
        else            
          raise PeriodNotFound, "No time period found for #{utc}"
        end
      end
    else
      raise PeriodNotFound, "No time period found for #{utc}"
    end
  }
end

#utc_to_local(utc) ⇒ `Object`

Converts a time in UTC to the local timezone. utc can either be a DateTime or a Time. 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 172

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

Class: TZInfo::Timezone

Overview

Direct Known Subclasses

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

#current_period ⇒ Object

#current_period_and_time ⇒ Object

#identifier ⇒ Object

#local_to_utc(local) ⇒ Object

#now ⇒ Object

#period_for_local(local) ⇒ Object

#period_for_utc(utc) ⇒ Object

#utc_to_local(utc) ⇒ Object