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 486 486: def self._load(data) 487: Timezone.get(data) 488: 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 135 135: def self.all 136: get_proxies(all_identifiers) 137: 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 194 194: def self.all_country_zone_identifiers 195: Country.all_codes.inject([]) {|zones,country| 196: zones += Country.get(country).zone_identifiers 197: } 198: 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 184 184: def self.all_country_zones 185: Country.all_codes.inject([]) {|zones,country| 186: zones += Country.get(country).zones 187: } 188: 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 157 157: def self.all_data_zone_identifiers 158: load_index 159: Indexes::Timezones.data_timezones 160: 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 151 151: def self.all_data_zones 152: get_proxies(all_data_zone_identifiers) 153: end
Returns an array containing the identifiers of all the available Timezones.
# File lib/tzinfo/timezone.rb, line 141 141: def self.all_identifiers 142: load_index 143: Indexes::Timezones.timezones 144: end
Returns an array containing the identifiers of all the available Timezones that are links to other Timezones.
# File lib/tzinfo/timezone.rb, line 173 173: def self.all_linked_zone_identifiers 174: load_index 175: Indexes::Timezones.linked_timezones 176: 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 167 167: def self.all_linked_zones 168: get_proxies(all_linked_zone_identifiers) 169: 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 75 75: def self.get(identifier) 76: instance = @@loaded_zones[identifier] 77: unless instance 78: raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-Za-z0-9\+\-_]+(\/[A-Za-z0-9\+\-_]+)*$/ 79: identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__') 80: begin 81: # Use a temporary variable to avoid an rdoc warning 82: file = "tzinfo/definitions/#{identifier}".untaint 83: require file 84: 85: m = Definitions 86: identifier.split(/\//).each {|part| 87: m = m.const_get(part) 88: } 89: 90: info = m.get 91: 92: # Could make Timezone subclasses register an interest in an info 93: # type. Since there are currently only two however, there isn't 94: # much point. 95: if info.kind_of?(DataTimezoneInfo) 96: instance = DataTimezone.new(info) 97: elsif info.kind_of?(LinkedTimezoneInfo) 98: instance = LinkedTimezone.new(info) 99: else 100: raise InvalidTimezoneIdentifier, "No handler for info type #{info.class}" 101: end 102: 103: @@loaded_zones[instance.identifier] = instance 104: rescue LoadError, NameError => e 105: raise InvalidTimezoneIdentifier, e.message 106: end 107: end 108: 109: instance 110: 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 117 117: def self.get_proxy(identifier) 118: TimezoneProxy.new(identifier) 119: 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 123 123: def self.new(identifier = nil) 124: if identifier 125: get(identifier) 126: else 127: super() 128: end 129: end
Returns all US zone identifiers. A shortcut for TZInfo::Country.get(‘US’).zone_identifiers.
# File lib/tzinfo/timezone.rb, line 211 211: def self.us_zone_identifiers 212: Country.get('US').zone_identifiers 213: 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 205 205: def self.us_zones 206: Country.get('US').zones 207: 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 465 465: def <=>(tz) 466: identifier <=> tz.identifier 467: end
Dumps this Timezone for marshalling.
# File lib/tzinfo/timezone.rb, line 481 481: def _dump(limit) 482: identifier 483: end
Returns the TimezonePeriod for the current time.
# File lib/tzinfo/timezone.rb, line 427 427: def current_period 428: period_for_utc(Time.now.utc) 429: 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 433 433: def current_period_and_time 434: utc = Time.now.utc 435: period = period_for_utc(utc) 436: [period.to_local(utc), period] 437: 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 471 471: def eql?(tz) 472: self == tz 473: 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 246 246: def friendly_identifier(skip_first_part = false) 247: parts = identifier.split('/') 248: if parts.empty? 249: # shouldn't happen 250: identifier 251: elsif parts.length == 1 252: parts[0] 253: else 254: if skip_first_part 255: result = '' 256: else 257: result = parts[0] + ' - ' 258: end 259: 260: parts[1, parts.length - 1].reverse_each {|part| 261: part.gsub!(/_/, ' ') 262: 263: if part.index(/[a-z]/) 264: # Missing a space if a lower case followed by an upper case and the 265: # name isn't McXxxx. 266: part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2') 267: part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2') 268: 269: # Missing an apostrophe if two consecutive upper case characters. 270: part.gsub!(/([A-Z])([A-Z])/, '\1\\2') 271: end 272: 273: result << part 274: result << ', ' 275: } 276: 277: result.slice!(result.length - 2, 2) 278: result 279: end 280: end
Returns a hash of this Timezone.
# File lib/tzinfo/timezone.rb, line 476 476: def hash 477: identifier.hash 478: end
The identifier of the timezone, e.g. “Europe/Paris“.
# File lib/tzinfo/timezone.rb, line 216 216: def identifier 217: raise UnknownTimezone, 'TZInfo::Timezone constructed directly' 218: end
Returns internal object state as a programmer-readable string.
# File lib/tzinfo/timezone.rb, line 232 232: def inspect 233: "#<#{self.class}: #{identifier}>" 234: 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.
# File lib/tzinfo/timezone.rb, line 409 409: def local_to_utc(local, dst = nil) 410: TimeOrDateTime.wrap(local) {|wrapped| 411: if block_given? 412: period = period_for_local(wrapped, dst) {|periods| yield periods } 413: else 414: period = period_for_local(wrapped, dst) 415: end 416: 417: period.to_utc(wrapped) 418: } 419: end
An alias for identifier.
# File lib/tzinfo/timezone.rb, line 221 221: def name 222: # Don't use alias, as identifier gets overridden. 223: identifier 224: end
Returns the current time in the timezone as a Time.
# File lib/tzinfo/timezone.rb, line 422 422: def now 423: utc_to_local(Time.now.utc) 424: 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.
# File lib/tzinfo/timezone.rb, line 331 331: def period_for_local(local, dst = nil) 332: results = periods_for_local(local) 333: 334: if results.empty? 335: raise PeriodNotFound 336: elsif results.size < 2 337: results.first 338: else 339: # ambiguous result try to resolve 340: 341: if !dst.nil? 342: matches = results.find_all {|period| period.dst? == dst} 343: results = matches if !matches.empty? 344: end 345: 346: if results.size < 2 347: results.first 348: else 349: # still ambiguous, try the block 350: 351: if block_given? 352: results = yield results 353: end 354: 355: if results.is_a?(TimezonePeriod) 356: results 357: elsif results && results.size == 1 358: results.first 359: else 360: raise AmbiguousTime, "#{local} is an ambiguous local time." 361: end 362: end 363: end 364: 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 285 285: def period_for_utc(utc) 286: raise UnknownTimezone, 'TZInfo::Timezone constructed directly' 287: 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 293 293: def periods_for_local(local) 294: raise UnknownTimezone, 'TZInfo::Timezone constructed directly' 295: 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 445 445: def strftime(format, utc = Time.now.utc) 446: period = period_for_utc(utc) 447: local = period.to_local(utc) 448: local = Time.at(local).utc unless local.kind_of?(Time) || local.kind_of?(DateTime) 449: abbreviation = period.abbreviation.to_s.gsub(/%/, '%%') 450: 451: format = format.gsub(/(.?)%Z/) do 452: if $1 == '%' 453: # return %%Z so the real strftime treats it as a literal %Z too 454: '%%Z' 455: else 456: "#$1#{abbreviation}" 457: end 458: end 459: 460: local.strftime(format) 461: end
Returns a friendlier version of the identifier.
# File lib/tzinfo/timezone.rb, line 227 227: def to_s 228: friendly_identifier 229: 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 370 370: def utc_to_local(utc) 371: TimeOrDateTime.wrap(utc) {|wrapped| 372: period_for_utc(wrapped).to_local(wrapped) 373: } 374: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.