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)
Loads a marshalled Timezone.
# File lib/tzinfo/timezone.rb, line 516 516: def self._load(data) 517: Timezone.get(data) 518: 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.
# File lib/tzinfo/timezone.rb, line 155 155: def self.all 156: get_proxies(all_identifiers) 157: 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.
# File lib/tzinfo/timezone.rb, line 214 214: def self.all_country_zone_identifiers 215: Country.all_codes.inject([]) {|zones,country| 216: zones += Country.get(country).zone_identifiers 217: } 218: 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.
# File lib/tzinfo/timezone.rb, line 204 204: def self.all_country_zones 205: Country.all_codes.inject([]) {|zones,country| 206: zones += Country.get(country).zones 207: } 208: end
Returns an array containing the identifiers of all the available Timezones that are based on data (are not links to other Timezones)..
# File lib/tzinfo/timezone.rb, line 177 177: def self.all_data_zone_identifiers 178: load_index 179: Indexes::Timezones.data_timezones 180: 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.
# File lib/tzinfo/timezone.rb, line 171 171: def self.all_data_zones 172: get_proxies(all_data_zone_identifiers) 173: end
Returns an array containing the identifiers of all the available Timezones.
# File lib/tzinfo/timezone.rb, line 161 161: def self.all_identifiers 162: load_index 163: Indexes::Timezones.timezones 164: end
Returns an array containing the identifiers of all the available Timezones that are links to other Timezones.
# File lib/tzinfo/timezone.rb, line 193 193: def self.all_linked_zone_identifiers 194: load_index 195: Indexes::Timezones.linked_timezones 196: 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.
# File lib/tzinfo/timezone.rb, line 187 187: def self.all_linked_zones 188: get_proxies(all_linked_zone_identifiers) 189: end
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.
# File lib/tzinfo/timezone.rb, line 87 87: def self.default_dst 88: @@default_dst 89: end
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.
# File lib/tzinfo/timezone.rb, line 80 80: def self.default_dst=(value) 81: @@default_dst = value.nil? ? nil : !!value 82: end
Returns a timezone by its identifier (e.g. “Europe/London“, “America/Chicago“ or “UTC”).
Raises InvalidTimezoneIdentifier if the timezone couldn’t be found.
# File lib/tzinfo/timezone.rb, line 95 95: def self.get(identifier) 96: instance = @@loaded_zones[identifier] 97: unless instance 98: raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-Za-z0-9\+\-_]+(\/[A-Za-z0-9\+\-_]+)*$/ 99: identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__') 100: begin 101: # Use a temporary variable to avoid an rdoc warning 102: file = "tzinfo/definitions/#{identifier}".untaint 103: require file 104: 105: m = Definitions 106: identifier.split(/\//).each {|part| 107: m = m.const_get(part) 108: } 109: 110: info = m.get 111: 112: # Could make Timezone subclasses register an interest in an info 113: # type. Since there are currently only two however, there isn't 114: # much point. 115: if info.kind_of?(DataTimezoneInfo) 116: instance = DataTimezone.new(info) 117: elsif info.kind_of?(LinkedTimezoneInfo) 118: instance = LinkedTimezone.new(info) 119: else 120: raise InvalidTimezoneIdentifier, "No handler for info type #{info.class}" 121: end 122: 123: @@loaded_zones[instance.identifier] = instance 124: rescue LoadError, NameError => e 125: raise InvalidTimezoneIdentifier, e.message 126: end 127: end 128: 129: instance 130: 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.
# File lib/tzinfo/timezone.rb, line 137 137: def self.get_proxy(identifier) 138: TimezoneProxy.new(identifier) 139: end
If identifier is nil calls super(), otherwise calls get. An identfier should always be passed in when called externally.
# File lib/tzinfo/timezone.rb, line 143 143: def self.new(identifier = nil) 144: if identifier 145: get(identifier) 146: else 147: super() 148: end 149: end
Returns all US zone identifiers. A shortcut for TZInfo::Country.get(‘US’).zone_identifiers.
# File lib/tzinfo/timezone.rb, line 231 231: def self.us_zone_identifiers 232: Country.get('US').zone_identifiers 233: 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.
# File lib/tzinfo/timezone.rb, line 225 225: def self.us_zones 226: Country.get('US').zones 227: 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.
# File lib/tzinfo/timezone.rb, line 495 495: def <=>(tz) 496: identifier <=> tz.identifier 497: end
Dumps this Timezone for marshalling.
# File lib/tzinfo/timezone.rb, line 511 511: def _dump(limit) 512: identifier 513: end
Returns the TimezonePeriod for the current time.
# File lib/tzinfo/timezone.rb, line 457 457: def current_period 458: period_for_utc(Time.now.utc) 459: end
Returns the current Time and TimezonePeriod as an array. The first element is the time, the second element is the period.
# File lib/tzinfo/timezone.rb, line 463 463: def current_period_and_time 464: utc = Time.now.utc 465: period = period_for_utc(utc) 466: [period.to_local(utc), period] 467: end
Returns true if and only if the identifier of tz is equal to the identifier of this Timezone.
# File lib/tzinfo/timezone.rb, line 501 501: def eql?(tz) 502: self == tz 503: 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"
# File lib/tzinfo/timezone.rb, line 266 266: def friendly_identifier(skip_first_part = false) 267: parts = identifier.split('/') 268: if parts.empty? 269: # shouldn't happen 270: identifier 271: elsif parts.length == 1 272: parts[0] 273: else 274: if skip_first_part 275: result = '' 276: else 277: result = parts[0] + ' - ' 278: end 279: 280: parts[1, parts.length - 1].reverse_each {|part| 281: part.gsub!(/_/, ' ') 282: 283: if part.index(/[a-z]/) 284: # Missing a space if a lower case followed by an upper case and the 285: # name isn't McXxxx. 286: part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2') 287: part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2') 288: 289: # Missing an apostrophe if two consecutive upper case characters. 290: part.gsub!(/([A-Z])([A-Z])/, '\1\\2') 291: end 292: 293: result << part 294: result << ', ' 295: } 296: 297: result.slice!(result.length - 2, 2) 298: result 299: end 300: end
Returns a hash of this Timezone.
# File lib/tzinfo/timezone.rb, line 506 506: def hash 507: identifier.hash 508: end
The identifier of the timezone, e.g. “Europe/Paris“.
# File lib/tzinfo/timezone.rb, line 236 236: def identifier 237: raise UnknownTimezone, 'TZInfo::Timezone constructed directly' 238: end
Returns internal object state as a programmer-readable string.
# File lib/tzinfo/timezone.rb, line 252 252: def inspect 253: "#<#{self.class}: #{identifier}>" 254: 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.
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.
# File lib/tzinfo/timezone.rb, line 439 439: def local_to_utc(local, dst = Timezone.default_dst) 440: TimeOrDateTime.wrap(local) {|wrapped| 441: if block_given? 442: period = period_for_local(wrapped, dst) {|periods| yield periods } 443: else 444: period = period_for_local(wrapped, dst) 445: end 446: 447: period.to_utc(wrapped) 448: } 449: end
An alias for identifier.
# File lib/tzinfo/timezone.rb, line 241 241: def name 242: # Don't use alias, as identifier gets overridden. 243: identifier 244: end
Returns the current time in the timezone as a Time.
# File lib/tzinfo/timezone.rb, line 452 452: def now 453: utc_to_local(Time.now.utc) 454: 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.
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.
# File lib/tzinfo/timezone.rb, line 356 356: def period_for_local(local, dst = Timezone.default_dst) 357: results = periods_for_local(local) 358: 359: if results.empty? 360: raise PeriodNotFound 361: elsif results.size < 2 362: results.first 363: else 364: # ambiguous result try to resolve 365: 366: if !dst.nil? 367: matches = results.find_all {|period| period.dst? == dst} 368: results = matches if !matches.empty? 369: end 370: 371: if results.size < 2 372: results.first 373: else 374: # still ambiguous, try the block 375: 376: if block_given? 377: results = yield results 378: end 379: 380: if results.is_a?(TimezonePeriod) 381: results 382: elsif results && results.size == 1 383: results.first 384: else 385: raise AmbiguousTime, "#{local} is an ambiguous local time." 386: end 387: end 388: end 389: 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).
# File lib/tzinfo/timezone.rb, line 305 305: def period_for_utc(utc) 306: raise UnknownTimezone, 'TZInfo::Timezone constructed directly' 307: 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.
# File lib/tzinfo/timezone.rb, line 313 313: def periods_for_local(local) 314: raise UnknownTimezone, 'TZInfo::Timezone constructed directly' 315: 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).
# File lib/tzinfo/timezone.rb, line 475 475: def strftime(format, utc = Time.now.utc) 476: period = period_for_utc(utc) 477: local = period.to_local(utc) 478: local = Time.at(local).utc unless local.kind_of?(Time) || local.kind_of?(DateTime) 479: abbreviation = period.abbreviation.to_s.gsub(/%/, '%%') 480: 481: format = format.gsub(/(.?)%Z/) do 482: if $1 == '%' 483: # return %%Z so the real strftime treats it as a literal %Z too 484: '%%Z' 485: else 486: "#$1#{abbreviation}" 487: end 488: end 489: 490: local.strftime(format) 491: end
Returns a friendlier version of the identifier.
# File lib/tzinfo/timezone.rb, line 247 247: def to_s 248: friendly_identifier 249: 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).
# File lib/tzinfo/timezone.rb, line 395 395: def utc_to_local(utc) 396: TimeOrDateTime.wrap(utc) {|wrapped| 397: period_for_utc(wrapped).to_local(wrapped) 398: } 399: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.