Class TZInfo::Timezone
In: vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb
Parent: Object

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)

Methods

Included Modules

Comparable

Public Class methods

Loads a marshalled Timezone.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 489
489:     def self._load(data)
490:       Timezone.get(data)
491:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 138
138:     def self.all
139:       get_proxies(all_identifiers)
140:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 197
197:     def self.all_country_zone_identifiers
198:       Country.all_codes.inject([]) {|zones,country|
199:         zones += Country.get(country).zone_identifiers
200:       }
201:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 187
187:     def self.all_country_zones
188:       Country.all_codes.inject([]) {|zones,country|
189:         zones += Country.get(country).zones
190:       }
191:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 160
160:     def self.all_data_zone_identifiers
161:       load_index
162:       Indexes::Timezones.data_timezones
163:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 154
154:     def self.all_data_zones
155:       get_proxies(all_data_zone_identifiers)
156:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 144
144:     def self.all_identifiers
145:       load_index
146:       Indexes::Timezones.timezones
147:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 176
176:     def self.all_linked_zone_identifiers
177:       load_index
178:       Indexes::Timezones.linked_timezones
179:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 170
170:     def self.all_linked_zones
171:       get_proxies(all_linked_zone_identifiers)      
172:     end

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

Raises InvalidTimezoneIdentifier if the timezone couldn‘t be found.

[Source]

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 120
120:     def self.get_proxy(identifier)
121:       TimezoneProxy.new(identifier)
122:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 126
126:     def self.new(identifier = nil)
127:       if identifier        
128:         get(identifier)
129:       else
130:         super()
131:       end
132:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 214
214:     def self.us_zone_identifiers
215:       Country.get('US').zone_identifiers
216:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 208
208:     def self.us_zones
209:       Country.get('US').zones
210:     end

Public Instance methods

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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 468
468:     def <=>(tz)
469:       identifier <=> tz.identifier
470:     end

Dumps this Timezone for marshalling.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 484
484:     def _dump(limit)
485:       identifier
486:     end

Returns the TimezonePeriod for the current time.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 430
430:     def current_period
431:       period_for_utc(Time.now.utc)
432:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 436
436:     def current_period_and_time
437:       utc = Time.now.utc
438:       period = period_for_utc(utc)
439:       [period.to_local(utc), period]
440:     end
current_time_and_period()

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 474
474:     def eql?(tz)
475:       self == tz
476:     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"

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 249
249:     def friendly_identifier(skip_first_part = false)
250:       parts = identifier.split('/')
251:       if parts.empty?
252:         # shouldn't happen
253:         identifier
254:       elsif parts.length == 1        
255:         parts[0]
256:       else
257:         if skip_first_part
258:           result = ''
259:         else
260:           result = parts[0] + ' - '
261:         end
262:         
263:         parts[1, parts.length - 1].reverse_each {|part|
264:           part.gsub!(/_/, ' ')
265:           
266:           if part.index(/[a-z]/)
267:             # Missing a space if a lower case followed by an upper case and the
268:             # name isn't McXxxx.
269:             part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2')
270:             part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2')
271:             
272:             # Missing an apostrophe if two consecutive upper case characters.
273:             part.gsub!(/([A-Z])([A-Z])/, '\1\'\2')
274:           end
275:           
276:           result << part
277:           result << ', '
278:         }
279:         
280:         result.slice!(result.length - 2, 2)
281:         result
282:       end
283:     end

Returns a hash of this Timezone.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 479
479:     def hash
480:       identifier.hash
481:     end

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 219
219:     def identifier
220:       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
221:     end

Returns internal object state as a programmer-readable string.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 235
235:     def inspect
236:       "#<#{self.class}: #{identifier}>"
237:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 412
412:     def local_to_utc(local, dst = nil)
413:       TimeOrDateTime.wrap(local) {|wrapped|
414:         if block_given?
415:           period = period_for_local(wrapped, dst) {|periods| yield periods }
416:         else
417:           period = period_for_local(wrapped, dst)
418:         end
419:         
420:         period.to_utc(wrapped)
421:       }
422:     end

An alias for identifier.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 224
224:     def name
225:       # Don't use alias, as identifier gets overridden.
226:       identifier
227:     end

Returns the current time in the timezone as a Time.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 425
425:     def now
426:       utc_to_local(Time.now.utc)
427:     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.

[Source]

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

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 288
288:     def period_for_utc(utc)            
289:       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'      
290:     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.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 296
296:     def periods_for_local(local)
297:       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
298:     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).

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 448
448:     def strftime(format, utc = Time.now.utc)      
449:       period = period_for_utc(utc)
450:       local = period.to_local(utc)      
451:       local = Time.at(local).utc unless local.kind_of?(Time) || local.kind_of?(DateTime)
452:       abbreviation = period.abbreviation.to_s.gsub(/%/, '%%')
453:       
454:       format = format.gsub(/(.?)%Z/) do
455:         if $1 == '%'
456:           # return %%Z so the real strftime treats it as a literal %Z too
457:           '%%Z'
458:         else
459:           "#$1#{abbreviation}"
460:         end
461:       end
462:       
463:       local.strftime(format)
464:     end

Returns a friendlier version of the identifier.

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 230
230:     def to_s
231:       friendly_identifier
232:     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).

[Source]

     # File vendor/rails/activesupport/lib/active_support/vendor/tzinfo-0.3.12/tzinfo/timezone.rb, line 373
373:     def utc_to_local(utc)
374:       TimeOrDateTime.wrap(utc) {|wrapped|
375:         period_for_utc(wrapped).to_local(wrapped)
376:       }
377:     end

[Validate]