Class: TZInfo::Timezone

Inherits:
Object
  • Object
show all
Includes:
Comparable
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, 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 class is thread-safe. It is safe to use class and instance methods of Timezone in concurrently executing threads. Instances of Timezone can be shared across thread boundaries.

Direct Known Subclasses

TimezoneProxy

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

._load(data) ⇒ Object

Loads a marshalled Timezone.



642
643
644
 
# File 'lib/tzinfo/timezone.rb', line 642

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.



123
124
125
 
# File 'lib/tzinfo/timezone.rb', line 123

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.



179
180
181
182
183
 
# File 'lib/tzinfo/timezone.rb', line 179

def self.all_country_zone_identifiers
  Country.all_codes.inject([]) do |zones,country|
    zones += Country.get(country).zone_identifiers
  end.uniq
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.



169
170
171
172
173
 
# File 'lib/tzinfo/timezone.rb', line 169

def self.all_country_zones
  Country.all_codes.inject([]) do |zones,country|
    zones += Country.get(country).zones
  end.uniq
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)..



144
145
146
 
# File 'lib/tzinfo/timezone.rb', line 144

def self.all_data_zone_identifiers
  data_source.data_timezone_identifiers
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.



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

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.



129
130
131
 
# File 'lib/tzinfo/timezone.rb', line 129

def self.all_identifiers
  data_source.timezone_identifiers
end

.all_linked_zone_identifiers ⇒ Object

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



159
160
161
 
# File 'lib/tzinfo/timezone.rb', line 159

def self.all_linked_zone_identifiers
  data_source.linked_timezone_identifiers
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.



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

def self.all_linked_zones
  get_proxies(all_linked_zone_identifiers)      
end

.default_dst ⇒ Object

Gets the default value of the optional dst parameter of the local_to_utc and period_for_local methods. Can be set to nil, true or false.



73
74
75
 
# File 'lib/tzinfo/timezone.rb', line 73

def self.default_dst
  @@default_dst
end

.default_dst=(value) ⇒ Object

Sets the default value of the optional dst parameter of the local_to_utc and period_for_local methods. Can be set to nil, true or false.

The value of default_dst defaults to nil if unset.



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

def self.default_dst=(value)
  @@default_dst = value.nil? ? nil : !!value
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.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/tzinfo/timezone.rb', line 81

def self.get(identifier)
  instance = @@loaded_zones[identifier]
  
  unless instance
    # Thread-safety: It is possible that multiple equivalent Timezone 
    # instances could be created here in concurrently executing threads. 
    # The consequences of this are that the data may be loaded more than 
    # once (depending on the data source) and memoized calculations could
    # be discarded. The performance benefit of ensuring that only a single
    # instance is created is unlikely to be worth the overhead of only
    # allowing one Timezone to be loaded at a time.
    info = data_source.load_timezone_info(identifier)
    instance = info.create_timezone
    @@loaded_zones[instance.identifier] = instance         
  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.



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

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.



111
112
113
114
115
116
117
 
# File 'lib/tzinfo/timezone.rb', line 111

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.



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

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.



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

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.

Returns nil if tz is not comparable with Timezone instances.



620
621
622
623
 
# File 'lib/tzinfo/timezone.rb', line 620

def <=>(tz)
  return nil unless tz.is_a?(Timezone)
  identifier <=> tz.identifier
end

#_dump(limit) ⇒ Object

Dumps this Timezone for marshalling.



637
638
639
 
# File 'lib/tzinfo/timezone.rb', line 637

def _dump(limit)
  identifier
end

#canonical_identifier ⇒ Object

Returns the canonical identifier for this Timezone.

This is a shortcut for calling canonical_zone.identifier. Please refer to the canonical_zone documentation for further information.



532
533
534
 
# File 'lib/tzinfo/timezone.rb', line 532

def canonical_identifier
  canonical_zone.identifier
end

#canonical_zone ⇒ Object

Returns the canonical Timezone instance for this Timezone.

The IANA Time Zone database contains two types of definition: Zones and Links. Zones are defined by rules that set out when transitions occur. Links are just references to fully defined Zone, creating an alias for that Zone.

Links are commonly used where a time zone has been renamed in a release of the Time Zone database. For example, the Zone US/Eastern was renamed as America/New_York. A US/Eastern Link was added in its place, linking to (and creating an alias for) for America/New_York.

Links are also used for time zones that are currently identical to a full Zone, but that are administered seperately. For example, Europe/Vatican is a Link to (and alias for) Europe/Rome.

For a full Zone, canonical_zone returns self.

For a Link, canonical_zone returns a Timezone instance representing the full Zone that the link targets.

TZInfo can be used with different data sources (see the documentation for TZInfo::DataSource). Please note that some DataSource implementations may not support distinguishing between full Zones and Links and will treat all time zones as full Zones. In this case, the canonical_zone will always return self.

There are two built-in DataSource implementations. RubyDataSource (which will be used if the tzinfo-data gem is available) supports Link zones. ZoneinfoDataSource returns Link zones as if they were full Zones. If the canonical_zone or canonical_identifier methods are required, the tzinfo-data gem should be installed.

The TZInfo::DataSource.get method can be used to check which DataSource implementation is being used.



337
338
339
 
# File 'lib/tzinfo/timezone.rb', line 337

def canonical_zone
  raise_unknown_timezone
end

#current_period ⇒ Object

Returns the TimezonePeriod for the current time.



542
543
544
 
# File 'lib/tzinfo/timezone.rb', line 542

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.



548
549
550
551
552
 
# File 'lib/tzinfo/timezone.rb', line 548

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) 


627
628
629
 
# File 'lib/tzinfo/timezone.rb', line 627

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"



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

def friendly_identifier(skip_first_part = false)
  parts = identifier.split('/')
  if parts.empty?
    # shouldn't happen
    identifier
  elsif parts.length == 1        
    parts[0]
  else
    prefix = skip_first_part ? nil : "#{parts[0]} - "

    parts = parts.drop(1).map do |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

      part
    end

    "#{prefix}#{parts.reverse.join(', ')}"
  end
end

#hash ⇒ Object

Returns a hash of this Timezone.



632
633
634
 
# File 'lib/tzinfo/timezone.rb', line 632

def hash
  identifier.hash
end

#identifier ⇒ Object

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



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

def identifier
  raise_unknown_timezone
end

#inspect ⇒ Object

Returns internal object state as a programmer-readable string.



217
218
219
 
# File 'lib/tzinfo/timezone.rb', line 217

def inspect
  "#<#{self.class}: #{identifier}>"
end

#local_to_utc(local, dst = Timezone.default_dst) ⇒ 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.

The default value of the dst parameter can be specified by setting Timezone.default_dst. If default_dst is not set, or is set to nil, then an AmbiguousTime exception will be raised in ambiguous situations unless a block is given to resolve the ambiguity.



463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/tzinfo/timezone.rb', line 463

def local_to_utc(local, dst = Timezone.default_dst)
  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.



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

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

#now ⇒ Object

Returns the current time in the timezone as a Time.



537
538
539
 
# File 'lib/tzinfo/timezone.rb', line 537

def now
  utc_to_local(Time.now.utc)
end

#offsets_up_to(utc_to, utc_from = nil) ⇒ Object

Returns information about offsets used by the Timezone up to a given date and time, specified using UTC (utc_to). The information is returned as an Array of TimezoneOffset instances.

A from date and time may also be supplied using the utc_from parameter (also specified in UTC). If utc_from is not nil, only offsets used from that date and time forward will be returned.

Comparisons with utc_to are exclusive. Comparisons with utc_from are inclusive.

Offsets may be returned in any order.

utc_to and utc_from can be specified using either DateTime, Time or integer timestamps (Time.to_i).

If utc_from is specified and utc_to is not greater than utc_from, then offsets_up_to raises an ArgumentError exception.



493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
 
# File 'lib/tzinfo/timezone.rb', line 493

def offsets_up_to(utc_to, utc_from = nil)
  utc_to = TimeOrDateTime.wrap(utc_to)
  transitions = transitions_up_to(utc_to, utc_from)
  
  if transitions.empty?
    # No transitions in the range, find the period that covers it.

    if utc_from
      # Use the from date as it is inclusive.
      period = period_for_utc(utc_from)
    else
      # utc_to is exclusive, so this can't be used with period_for_utc.
      # However, any time earlier than utc_to can be used.
      
      # Subtract 1 hour (since this is one of the cached OffsetRationals).
      # Use add_with_convert so that conversion to DateTime is performed if
      # required.
      period = period_for_utc(utc_to.add_with_convert(-3600))
    end
  
    [period.offset]
  else
    result = Set.new
    
    first = transitions.first        
    result << first.previous_offset unless utc_from && first.at == utc_from
    
    transitions.each do |t|
      result << t.offset
    end
    
    result.to_a
  end
end

#period_for_local(local, dst = Timezone.default_dst) ⇒ 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.

The default value of the dst parameter can be specified by setting Timezone.default_dst. If default_dst is not set, or is set to nil, then an AmbiguousTime exception will be raised in ambiguous situations unless a block is given to resolve the ambiguity.



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

def period_for_local(local, dst = Timezone.default_dst)
  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).



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

def period_for_utc(utc)            
  raise_unknown_timezone
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.



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

def periods_for_local(local)
  raise_unknown_timezone
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 and %z are replaced with the timezone abbreviation (for example, EST or EDT) and offset for the specified Timezone and time.

The offset can be formatted as follows:

  • %z - hour and minute (e.g. +0500)

  • %:z - hour and minute separated with a colon (e.g. +05:00)

  • %::z - hour minute and second separated with colons (e.g. +05:00:00)

  • %:::z - hour only (e.g. +05)

Timezone#strftime currently handles the replacement of %z. From TZInfo version 2.0.0, %z will be passed to Time#strftime and DateTime#strftime instead. Some of the formatting options may cease to be available depending on the version of Ruby in use (for example, %:::z is only supported by Time#strftime from MRI version 2.0.0 onwards.)



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
 
# File 'lib/tzinfo/timezone.rb', line 575

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|:*z)/) do
    if $1.length.odd?
      # Escaped literal percent or series of percents. Pass on to strftime.          
      "#$1%#$2"
    elsif $2 == "Z"
      "#$1#{abbreviation}"
    else
      m, s = period.utc_total_offset.divmod(60)
      h, m = m.divmod(60)
      case $2.length
      when 1
        "#$1#{'%+03d%02d' % [h,m]}"
      when 2
        "#$1#{'%+03d:%02d' % [h,m]}"
      when 3
        "#$1#{'%+03d:%02d:%02d' % [h,m,s]}"
      when 4
        "#$1#{'%+03d' % [h]}"
      else # more than 3 colons - not a valid option
        # Passing the invalid format string through to Time#strftime or
        # DateTime#strtime would normally result in it being returned in the
        # result. However, with Ruby 1.8.7 on Windows (as tested with Ruby
        # 1.8.7-p374 from http://rubyinstaller.org/downloads/archives), this
        # causes Time#strftime to always return an empty string (e.g.
        # Time.now.strftime('a %::::z b') returns '').
        #
        # Escape the percent to force it to be evaluated as a literal.
        "#$1%%#$2"
      end
    end
  end
  
  local.strftime(format)
end

#to_s ⇒ Object

Returns a friendlier version of the identifier.



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

def to_s
  friendly_identifier
end

#transitions_up_to(utc_to, utc_from = nil) ⇒ Object

Returns an Array of TimezoneTransition instances representing the times where the UTC offset of the timezone changes.

Transitions are returned up to a given date and time up to a given date and time, specified in UTC (utc_to).

A from date and time may also be supplied using the utc_from parameter (also specified in UTC). If utc_from is not nil, only transitions from that date and time onwards will be returned.

Comparisons with utc_to are exclusive. Comparisons with utc_from are inclusive. If a transition falls precisely on utc_to, it will be excluded. If a transition falls on utc_from, it will be included.

Transitions returned are ordered by when they occur, from earliest to latest.

utc_to and utc_from can be specified using either DateTime, Time or integer timestamps (Time.to_i).

If utc_from is specified and utc_to is not greater than utc_from, then transitions_up_to raises an ArgumentError exception.



298
299
300
 
# File 'lib/tzinfo/timezone.rb', line 298

def transitions_up_to(utc_to, utc_from = nil)
  raise_unknown_timezone
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).



419
420
421
422
423
 
# File 'lib/tzinfo/timezone.rb', line 419

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