Source

RubyLearning / ProjectTrak / vendor / rails / activesupport / lib / active_support / vendor / tzinfo-0.3.12 / tzinfo / timezone.rb

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
#--
# Copyright (c) 2005-2006 Philip Ross
# 
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
# 
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#++

require 'date'
# require 'tzinfo/country'
require 'tzinfo/time_or_datetime'
require 'tzinfo/timezone_period'

module TZInfo
  # Indicate a specified time in a local timezone has more than one
  # possible time in UTC. This happens when switching from daylight savings time 
  # to normal time where the clocks are rolled back. Thrown by period_for_local
  # and local_to_utc when using an ambiguous time and not specifying any 
  # means to resolve the ambiguity.
  class AmbiguousTime < StandardError
  end
  
  # Thrown to indicate that no TimezonePeriod matching a given time could be found.
  class PeriodNotFound < StandardError
  end
  
  # Thrown by Timezone#get if the identifier given is not valid.
  class InvalidTimezoneIdentifier < StandardError
  end
  
  # Thrown if an attempt is made to use a timezone created with Timezone.new(nil).
  class UnknownTimezone < StandardError
  end
  
  # 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 http://www.twinsun.com/tz/tz-link.htm)
  class Timezone
    include Comparable
    
    # Cache of loaded zones by identifier to avoid using require if a zone
    # has already been loaded.
    @@loaded_zones = {}
    
    # Whether the timezones index has been loaded yet.
    @@index_loaded = false
    
    # Returns a timezone by its identifier (e.g. "Europe/London", 
    # "America/Chicago" or "UTC").
    #
    # Raises InvalidTimezoneIdentifier if the timezone couldn't be found.
    def self.get(identifier)
      instance = @@loaded_zones[identifier]
      unless instance  
        raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-z0-9\+\-_]+(\/[A-z0-9\+\-_]+)*$/
        identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__')
        begin
          # Use a temporary variable to avoid an rdoc warning
          file = "tzinfo/definitions/#{identifier}"
          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 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. 
    def self.get_proxy(identifier)
      TimezoneProxy.new(identifier)
    end
    
    # If identifier is nil calls super(), otherwise calls get. An identfier 
    # should always be passed in when called externally.
    def self.new(identifier = nil)
      if identifier        
        get(identifier)
      else
        super()
      end
    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.
    def self.all
      get_proxies(all_identifiers)
    end
    
    # Returns an array containing the identifiers of all the available 
    # Timezones.
    def self.all_identifiers
      load_index
      Indexes::Timezones.timezones
    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.
    def self.all_data_zones
      get_proxies(all_data_zone_identifiers)
    end
    
    # Returns an array containing the identifiers of all the available 
    # Timezones that are based on data (are not links to other Timezones)..
    def self.all_data_zone_identifiers
      load_index
      Indexes::Timezones.data_timezones
    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.
    def self.all_linked_zones
      get_proxies(all_linked_zone_identifiers)      
    end
    
    # Returns an array containing the identifiers of all the available 
    # Timezones that are links to other Timezones.
    def self.all_linked_zone_identifiers
      load_index
      Indexes::Timezones.linked_timezones
    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.        
    def self.all_country_zones
      Country.all_codes.inject([]) {|zones,country|
        zones += Country.get(country).zones
      }
    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.
    def self.all_country_zone_identifiers
      Country.all_codes.inject([]) {|zones,country|
        zones += Country.get(country).zone_identifiers
      }
    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.
    def self.us_zones
      Country.get('US').zones
    end
    
    # Returns all US zone identifiers. A shortcut for 
    # TZInfo::Country.get('US').zone_identifiers.
    def self.us_zone_identifiers
      Country.get('US').zone_identifiers
    end
    
    # The identifier of the timezone, e.g. "Europe/Paris".
    def identifier
      raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
    end
    
    # An alias for identifier.
    def name
      # Don't use alias, as identifier gets overridden.
      identifier
    end
    
    # Returns a friendlier version of the identifier.
    def to_s
      friendly_identifier
    end
    
    # Returns internal object state as a programmer-readable string.
    def inspect
      "#<#{self.class}: #{identifier}>"
    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"           
    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 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).        
    def period_for_utc(utc)            
      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.
    def periods_for_local(local)
      raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
    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.
    def period_for_local(local, dst = nil)            
      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
    
    # 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).
    def utc_to_local(utc)
      TimeOrDateTime.wrap(utc) {|wrapped|
        period_for_utc(wrapped).to_local(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.
    def local_to_utc(local, dst = nil)
      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
    
    # Returns the current time in the timezone as a Time.
    def now
      utc_to_local(Time.now.utc)
    end
    
    # Returns the TimezonePeriod for the current time. 
    def current_period
      period_for_utc(Time.now.utc)
    end
    
    # Returns the current Time and TimezonePeriod as an array. The first element
    # is the time, the second element is the period.
    def current_period_and_time
      utc = Time.now.utc
      period = period_for_utc(utc)
      [period.to_local(utc), period]
    end
    
    alias :current_time_and_period :current_period_and_time

    # 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).        
    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
    
    # 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.
    def <=>(tz)
      identifier <=> tz.identifier
    end
    
    # Returns true if and only if the identifier of tz is equal to the 
    # identifier of this Timezone.
    def eql?(tz)
      self == tz
    end
    
    # Returns a hash of this Timezone.
    def hash
      identifier.hash
    end
    
    # Dumps this Timezone for marshalling.
    def _dump(limit)
      identifier
    end
    
    # Loads a marshalled Timezone.
    def self._load(data)
      Timezone.get(data)
    end
    
    private
      # Loads in the index of timezones if it hasn't already been loaded.
      def self.load_index
        unless @@index_loaded
          require 'tzinfo/indexes/timezones'
          @@index_loaded = true
        end        
      end
      
      # Returns an array of proxies corresponding to the given array of 
      # identifiers.
      def self.get_proxies(identifiers)
        identifiers.collect {|identifier| get_proxy(identifier)}
      end
  end        
end