Parent

Included Modules

Files

TZInfo::Timezone

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)

Public Class Methods

_load(data) click to toggle source

Loads a marshalled Timezone.

     # File lib/tzinfo/timezone.rb, line 486
486:     def self._load(data)
487:       Timezone.get(data)
488:     end
all() click to toggle source

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 135
135:     def self.all
136:       get_proxies(all_identifiers)
137:     end
all_country_zone_identifiers() click to toggle source

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 194
194:     def self.all_country_zone_identifiers
195:       Country.all_codes.inject([]) {|zones,country|
196:         zones += Country.get(country).zone_identifiers
197:       }
198:     end
all_country_zones() click to toggle source

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 184
184:     def self.all_country_zones
185:       Country.all_codes.inject([]) {|zones,country|
186:         zones += Country.get(country).zones
187:       }
188:     end
all_data_zone_identifiers() click to toggle source

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 157
157:     def self.all_data_zone_identifiers
158:       load_index
159:       Indexes::Timezones.data_timezones
160:     end
all_data_zones() click to toggle source

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 151
151:     def self.all_data_zones
152:       get_proxies(all_data_zone_identifiers)
153:     end
all_identifiers() click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 141
141:     def self.all_identifiers
142:       load_index
143:       Indexes::Timezones.timezones
144:     end
all_linked_zone_identifiers() click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 173
173:     def self.all_linked_zone_identifiers
174:       load_index
175:       Indexes::Timezones.linked_timezones
176:     end
all_linked_zones() click to toggle source

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 167
167:     def self.all_linked_zones
168:       get_proxies(all_linked_zone_identifiers)      
169:     end
get(identifier) click to toggle source

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 75
 75:     def self.get(identifier)
 76:       instance = @@loaded_zones[identifier]
 77:       unless instance  
 78:         raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-Za-z0-9\+\-_]+(\/[A-Za-z0-9\+\-_]+)*$/
 79:         identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__')
 80:         begin
 81:           # Use a temporary variable to avoid an rdoc warning
 82:           file = "tzinfo/definitions/#{identifier}".untaint
 83:           require file
 84:           
 85:           m = Definitions
 86:           identifier.split(/\//).each {|part|
 87:             m = m.const_get(part)
 88:           }
 89:           
 90:           info = m.get
 91:           
 92:           # Could make Timezone subclasses register an interest in an info
 93:           # type. Since there are currently only two however, there isn't
 94:           # much point.
 95:           if info.kind_of?(DataTimezoneInfo)
 96:             instance = DataTimezone.new(info)
 97:           elsif info.kind_of?(LinkedTimezoneInfo)
 98:             instance = LinkedTimezone.new(info)
 99:           else
100:             raise InvalidTimezoneIdentifier, "No handler for info type #{info.class}"
101:           end
102:           
103:           @@loaded_zones[instance.identifier] = instance         
104:         rescue LoadError, NameError => e
105:           raise InvalidTimezoneIdentifier, e.message
106:         end
107:       end
108:       
109:       instance
110:     end
get_proxy(identifier) click to toggle source

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 117
117:     def self.get_proxy(identifier)
118:       TimezoneProxy.new(identifier)
119:     end
new(identifier = nil) click to toggle source

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 123
123:     def self.new(identifier = nil)
124:       if identifier        
125:         get(identifier)
126:       else
127:         super()
128:       end
129:     end
us_zone_identifiers() click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 211
211:     def self.us_zone_identifiers
212:       Country.get('US').zone_identifiers
213:     end
us_zones() click to toggle source

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 205
205:     def self.us_zones
206:       Country.get('US').zones
207:     end

Private Class Methods

get_proxies(identifiers) click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 501
501:       def self.get_proxies(identifiers)
502:         identifiers.collect {|identifier| get_proxy(identifier)}
503:       end
load_index() click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 492
492:       def self.load_index
493:         unless @@index_loaded
494:           require 'tzinfo/indexes/timezones'
495:           @@index_loaded = true
496:         end        
497:       end

Public Instance Methods

<=>(tz) click to toggle source

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 465
465:     def <=>(tz)
466:       identifier <=> tz.identifier
467:     end
_dump(limit) click to toggle source

Dumps this Timezone for marshalling.

     # File lib/tzinfo/timezone.rb, line 481
481:     def _dump(limit)
482:       identifier
483:     end
current_period() click to toggle source

Returns the TimezonePeriod for the current time.

     # File lib/tzinfo/timezone.rb, line 427
427:     def current_period
428:       period_for_utc(Time.now.utc)
429:     end
current_period_and_time() click to toggle source

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 433
433:     def current_period_and_time
434:       utc = Time.now.utc
435:       period = period_for_utc(utc)
436:       [period.to_local(utc), period]
437:     end
Also aliased as: current_time_and_period
current_time_and_period() click to toggle source
eql?(tz) click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 471
471:     def eql?(tz)
472:       self == tz
473:     end
friendly_identifier(skip_first_part = false) click to toggle source

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 246
246:     def friendly_identifier(skip_first_part = false)
247:       parts = identifier.split('/')
248:       if parts.empty?
249:         # shouldn't happen
250:         identifier
251:       elsif parts.length == 1        
252:         parts[0]
253:       else
254:         if skip_first_part
255:           result = ''
256:         else
257:           result = parts[0] + ' - '
258:         end
259:         
260:         parts[1, parts.length - 1].reverse_each {|part|
261:           part.gsub!(/_/, ' ')
262:           
263:           if part.index(/[a-z]/)
264:             # Missing a space if a lower case followed by an upper case and the
265:             # name isn't McXxxx.
266:             part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2')
267:             part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2')
268:             
269:             # Missing an apostrophe if two consecutive upper case characters.
270:             part.gsub!(/([A-Z])([A-Z])/, '\1\\2')
271:           end
272:           
273:           result << part
274:           result << ', '
275:         }
276:         
277:         result.slice!(result.length - 2, 2)
278:         result
279:       end
280:     end
hash() click to toggle source

Returns a hash of this Timezone.

     # File lib/tzinfo/timezone.rb, line 476
476:     def hash
477:       identifier.hash
478:     end
identifier() click to toggle source

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

     # File lib/tzinfo/timezone.rb, line 216
216:     def identifier
217:       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
218:     end
inspect() click to toggle source

Returns internal object state as a programmer-readable string.

     # File lib/tzinfo/timezone.rb, line 232
232:     def inspect
233:       "#<#{self.class}: #{identifier}>"
234:     end
local_to_utc(local, dst = nil) click to toggle source

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.

     # File lib/tzinfo/timezone.rb, line 409
409:     def local_to_utc(local, dst = nil)
410:       TimeOrDateTime.wrap(local) {|wrapped|
411:         if block_given?
412:           period = period_for_local(wrapped, dst) {|periods| yield periods }
413:         else
414:           period = period_for_local(wrapped, dst)
415:         end
416:         
417:         period.to_utc(wrapped)
418:       }
419:     end
name() click to toggle source

An alias for identifier.

     # File lib/tzinfo/timezone.rb, line 221
221:     def name
222:       # Don't use alias, as identifier gets overridden.
223:       identifier
224:     end
now() click to toggle source

Returns the current time in the timezone as a Time.

     # File lib/tzinfo/timezone.rb, line 422
422:     def now
423:       utc_to_local(Time.now.utc)
424:     end
period_for_local(local, dst = nil) click to toggle source

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.

     # File lib/tzinfo/timezone.rb, line 331
331:     def period_for_local(local, dst = nil)            
332:       results = periods_for_local(local)
333:       
334:       if results.empty?
335:         raise PeriodNotFound
336:       elsif results.size < 2
337:         results.first
338:       else
339:         # ambiguous result try to resolve
340:         
341:         if !dst.nil?
342:           matches = results.find_all {|period| period.dst? == dst}
343:           results = matches if !matches.empty?            
344:         end
345:         
346:         if results.size < 2
347:           results.first
348:         else
349:           # still ambiguous, try the block
350:                     
351:           if block_given?
352:             results = yield results
353:           end
354:           
355:           if results.is_a?(TimezonePeriod)
356:             results
357:           elsif results && results.size == 1
358:             results.first
359:           else          
360:             raise AmbiguousTime, "#{local} is an ambiguous local time."
361:           end
362:         end
363:       end      
364:     end
period_for_utc(utc) click to toggle source

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 285
285:     def period_for_utc(utc)            
286:       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'      
287:     end
periods_for_local(local) click to toggle source

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 293
293:     def periods_for_local(local)
294:       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
295:     end
strftime(format, utc = Time.now.utc) click to toggle source

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 445
445:     def strftime(format, utc = Time.now.utc)      
446:       period = period_for_utc(utc)
447:       local = period.to_local(utc)      
448:       local = Time.at(local).utc unless local.kind_of?(Time) || local.kind_of?(DateTime)
449:       abbreviation = period.abbreviation.to_s.gsub(/%/, '%%')
450:       
451:       format = format.gsub(/(.?)%Z/) do
452:         if $1 == '%'
453:           # return %%Z so the real strftime treats it as a literal %Z too
454:           '%%Z'
455:         else
456:           "#$1#{abbreviation}"
457:         end
458:       end
459:       
460:       local.strftime(format)
461:     end
to_s() click to toggle source

Returns a friendlier version of the identifier.

     # File lib/tzinfo/timezone.rb, line 227
227:     def to_s
228:       friendly_identifier
229:     end
utc_to_local(utc) click to toggle source

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 370
370:     def utc_to_local(utc)
371:       TimeOrDateTime.wrap(utc) {|wrapped|
372:         period_for_utc(wrapped).to_local(wrapped)
373:       }
374:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.