Class: TZInfo::Timezone
- Inherits:
-
Object
- Object
- TZInfo::Timezone
- 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.
Direct Known Subclasses
Constant Summary collapse
- @@loaded_zones =
Cache of loaded zones by identifier to avoid using require if a zone has already been loaded.
{}
- @@default_dst =
Default value of the dst parameter of the local_to_utc and period_for_local methods.
nil
Class Method Summary collapse
-
._load(data) ⇒ Object
Loads a marshalled Timezone.
-
.all ⇒ Object
Returns an array containing all the available Timezones.
-
.all_country_zone_identifiers ⇒ Object
Returns all the zone identifiers defined for all Countries.
-
.all_country_zones ⇒ Object
Returns all the Timezones defined for all Countries.
-
.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)..
-
.all_data_zones ⇒ Object
Returns an array containing all the available Timezones that are based on data (are not links to other Timezones).
-
.all_identifiers ⇒ Object
Returns an array containing the identifiers of all the available Timezones.
-
.all_linked_zone_identifiers ⇒ Object
Returns an array containing the identifiers of all the available Timezones that are links to other Timezones.
-
.all_linked_zones ⇒ Object
Returns an array containing all the available Timezones that are links to other Timezones.
-
.default_dst ⇒ Object
Gets the default value of the optional dst parameter of the local_to_utc and period_for_local methods.
-
.default_dst=(value) ⇒ Object
Sets the default value of the optional dst parameter of the local_to_utc and period_for_local methods.
-
.get(identifier) ⇒ Object
Returns a timezone by its identifier (e.g. “Europe/London”, “America/Chicago” or “UTC”).
-
.get_proxy(identifier) ⇒ Object
Returns a proxy for the Timezone with the given identifier.
-
.new(identifier = nil) ⇒ Object
If identifier is nil calls super(), otherwise calls get.
-
.us_zone_identifiers ⇒ Object
Returns all US zone identifiers.
-
.us_zones ⇒ Object
Returns all US Timezone instances.
Instance Method Summary collapse
-
#<=>(tz) ⇒ Object
Compares two Timezones based on their identifier.
-
#_dump(limit) ⇒ Object
Dumps this Timezone for marshalling.
-
#current_period ⇒ Object
Returns the TimezonePeriod for the current time.
-
#current_period_and_time ⇒ Object
(also: #current_time_and_period)
Returns the current Time and TimezonePeriod as an array.
-
#eql?(tz) ⇒ Boolean
Returns true if and only if the identifier of tz is equal to the identifier of this Timezone.
-
#friendly_identifier(skip_first_part = false) ⇒ Object
Returns a friendlier version of the identifier.
-
#hash ⇒ Object
Returns a hash of this Timezone.
-
#identifier ⇒ Object
The identifier of the timezone, e.g.
-
#inspect ⇒ Object
Returns internal object state as a programmer-readable string.
-
#local_to_utc(local, dst = Timezone.default_dst) ⇒ Object
Converts a time in the local timezone to UTC.
-
#name ⇒ Object
An alias for identifier.
-
#now ⇒ Object
Returns the current time in the timezone as a Time.
-
#period_for_local(local, dst = Timezone.default_dst) ⇒ Object
Returns the TimezonePeriod for the given local time.
-
#period_for_utc(utc) ⇒ Object
Returns the TimezonePeriod for the given UTC time.
-
#periods_for_local(local) ⇒ Object
Returns the set of TimezonePeriod instances that are valid for the given local time as an array.
-
#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.
-
#to_s ⇒ Object
Returns a friendlier version of the identifier.
-
#utc_to_local(utc) ⇒ Object
Converts a time in UTC to the local timezone.
Class Method Details
._load(data) ⇒ Object
Loads a marshalled Timezone.
486 487 488 |
# File 'lib/tzinfo/timezone.rb', line 486 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.
128 129 130 |
# File 'lib/tzinfo/timezone.rb', line 128 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.
184 185 186 187 188 |
# File 'lib/tzinfo/timezone.rb', line 184 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.
174 175 176 177 178 |
# File 'lib/tzinfo/timezone.rb', line 174 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)..
149 150 151 |
# File 'lib/tzinfo/timezone.rb', line 149 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.
143 144 145 |
# File 'lib/tzinfo/timezone.rb', line 143 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.
134 135 136 |
# File 'lib/tzinfo/timezone.rb', line 134 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.
164 165 166 |
# File 'lib/tzinfo/timezone.rb', line 164 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.
158 159 160 |
# File 'lib/tzinfo/timezone.rb', line 158 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.
85 86 87 |
# File 'lib/tzinfo/timezone.rb', line 85 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.
78 79 80 |
# File 'lib/tzinfo/timezone.rb', line 78 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.
93 94 95 96 97 98 99 100 101 102 103 |
# File 'lib/tzinfo/timezone.rb', line 93 def self.get(identifier) instance = @@loaded_zones[identifier] unless instance 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.
110 111 112 |
# File 'lib/tzinfo/timezone.rb', line 110 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.
116 117 118 119 120 121 122 |
# File 'lib/tzinfo/timezone.rb', line 116 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.
201 202 203 |
# File 'lib/tzinfo/timezone.rb', line 201 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.
195 196 197 |
# File 'lib/tzinfo/timezone.rb', line 195 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.
465 466 467 |
# File 'lib/tzinfo/timezone.rb', line 465 def <=>(tz) identifier <=> tz.identifier end |
#_dump(limit) ⇒ Object
Dumps this Timezone for marshalling.
481 482 483 |
# File 'lib/tzinfo/timezone.rb', line 481 def _dump(limit) identifier end |
#current_period ⇒ Object
Returns the TimezonePeriod for the current time.
427 428 429 |
# File 'lib/tzinfo/timezone.rb', line 427 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.
433 434 435 436 437 |
# File 'lib/tzinfo/timezone.rb', line 433 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.
471 472 473 |
# File 'lib/tzinfo/timezone.rb', line 471 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"
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 |
# File 'lib/tzinfo/timezone.rb', line 236 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.
476 477 478 |
# File 'lib/tzinfo/timezone.rb', line 476 def hash identifier.hash end |
#identifier ⇒ Object
The identifier of the timezone, e.g. “Europe/Paris”.
206 207 208 |
# File 'lib/tzinfo/timezone.rb', line 206 def identifier raise UnknownTimezone, 'TZInfo::Timezone constructed directly' end |
#inspect ⇒ Object
Returns internal object state as a programmer-readable string.
222 223 224 |
# File 'lib/tzinfo/timezone.rb', line 222 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.
409 410 411 412 413 414 415 416 417 418 419 |
# File 'lib/tzinfo/timezone.rb', line 409 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.
211 212 213 214 |
# File 'lib/tzinfo/timezone.rb', line 211 def name # Don't use alias, as identifier gets overridden. identifier end |
#now ⇒ Object
Returns the current time in the timezone as a Time.
422 423 424 |
# File 'lib/tzinfo/timezone.rb', line 422 def now utc_to_local(Time.now.utc) 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.
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 |
# File 'lib/tzinfo/timezone.rb', line 326 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).
275 276 277 |
# File 'lib/tzinfo/timezone.rb', line 275 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.
283 284 285 |
# File 'lib/tzinfo/timezone.rb', line 283 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).
445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 |
# File 'lib/tzinfo/timezone.rb', line 445 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.
217 218 219 |
# File 'lib/tzinfo/timezone.rb', line 217 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).
365 366 367 368 369 |
# File 'lib/tzinfo/timezone.rb', line 365 def utc_to_local(utc) TimeOrDateTime.wrap(utc) {|wrapped| period_for_utc(wrapped).to_local(wrapped) } end |