Class: TimeCrisis::TZInfo::Timezone

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/time_crisis/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

InfoTimezone, TimezoneProxy

Constant Summary collapse

@@loaded_zones =

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

{}
@@index_loaded =

Whether the timezones index has been loaded yet.

false

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

._load(data) ⇒ Object

Loads a marshalled Timezone.



466
467
468
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 466

def self._load(data)
  Timezone.get(data)
end

.all ⇒ Object

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.



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

def self.all
  get_proxies(all_identifiers)
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.



174
175
176
177
178
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 174

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.



164
165
166
167
168
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 164

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

.all_data_zone_identifiers ⇒ Object

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



137
138
139
140
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 137

def self.all_data_zone_identifiers
  load_index
  Indexes::Timezones.data_timezones
end

.all_data_zones ⇒ Object

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.



131
132
133
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 131

def self.all_data_zones
  get_proxies(all_data_zone_identifiers)
end

.all_identifiers ⇒ Object

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



121
122
123
124
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 121

def self.all_identifiers
  load_index
  Indexes::Timezones.timezones
end

.all_linked_zone_identifiers ⇒ Object

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



153
154
155
156
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 153

def self.all_linked_zone_identifiers
  load_index
  Indexes::Timezones.linked_timezones
end

.all_linked_zones ⇒ Object

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.



147
148
149
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 147

def self.all_linked_zones
  get_proxies(all_linked_zone_identifiers)
end

.get(identifier) ⇒ Object

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

Raises InvalidTimezoneIdentifier if the timezone couldn’t be found.



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
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 55

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 = "time_crisis/tzinfo/definitions/#{identifier}".untaint
      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

.get_proxy(identifier) ⇒ Object

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.



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

def self.get_proxy(identifier)
  TimezoneProxy.new(identifier)
end

.new(identifier = nil) ⇒ Object

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



103
104
105
106
107
108
109
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 103

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.



191
192
193
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 191

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.



185
186
187
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 185

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

Instance Method Details

#<=>(tz) ⇒ Object

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.



445
446
447
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 445

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

#_dump(limit) ⇒ Object

Dumps this Timezone for marshalling.



461
462
463
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 461

def _dump(limit)
  identifier
end

#current_period ⇒ Object

Returns the TimezonePeriod for the current time.



407
408
409
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 407

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.



413
414
415
416
417
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 413

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

#eql?(tz) ⇒ Boolean

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

Returns:

  • (Boolean) 


451
452
453
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 451

def eql?(tz)
  self == tz
end

#friendly_identifier(skip_first_part = false) ⇒ Object

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"



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
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 226

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

#hash ⇒ Object

Returns a hash of this Timezone.



456
457
458
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 456

def hash
  identifier.hash
end

#identifier ⇒ Object

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

Raises:



196
197
198
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 196

def identifier
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
end

#inspect ⇒ Object

Returns internal object state as a programmer-readable string.



212
213
214
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 212

def inspect
  "#<#{self.class}: #{identifier}>"
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 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.



389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 389

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

#name ⇒ Object

An alias for identifier.



201
202
203
204
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 201

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

#now ⇒ Object

Returns the current time in the timezone as a Time.



402
403
404
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 402

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

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.



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
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 311

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

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

Raises:



265
266
267
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 265

def period_for_utc(utc)
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
end

#periods_for_local(local) ⇒ Object

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.

Raises:



273
274
275
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 273

def periods_for_local(local)
  raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
end

#strftime(format, utc = Time.now.utc) ⇒ Object

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



425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 425

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

#to_s ⇒ Object

Returns a friendlier version of the identifier.



207
208
209
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 207

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



350
351
352
353
354
 
# File 'lib/time_crisis/tzinfo/timezone.rb', line 350

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