- Inheritance
- < Object
- Included Modules
- Comparable
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)
Methods
Class
| Visibility | Signature |
|---|---|
| public | _load (data) |
| public | all () |
| public | all_country_zone_identifiers () |
| public | all_country_zones () |
| public | all_data_zone_identifiers () |
| public | all_data_zones () |
| public | all_identifiers () |
| public | all_linked_zone_identifiers () |
| public | all_linked_zones () |
| public | get (identifier) |
| public | get_proxy (identifier) |
| public | new (identifier = nil) |
| public | us_zone_identifiers () |
| public | us_zones () |
Instance
| Visibility | Signature |
|---|---|
| public | <=> (tz) |
| public | _dump (limit) |
| public | current_period () |
| public | current_period_and_time () |
| public | current_time_and_period () |
| public | eql? (tz) |
| public | friendly_identifier (skip_first_part = false) |
| public | hash () |
| public | identifier () |
| public | inspect () |
| public | local_to_utc (local, dst = nil) {|periods| ...} |
| public | name () |
| public | now () |
| public | period_for_local (local, dst = nil) {|results| ...} |
| public | period_for_utc (utc) |
| public | periods_for_local (local) |
| public | strftime (format, utc = Time.now.utc) |
| public | to_s () |
| public | utc_to_local (utc) |
Class Method Detail
_load(data)
Loads a marshalled Timezone.
all()
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.
all_country_zone_identifiers()
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.
all_country_zones()
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.
all_data_zone_identifiers()
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()
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.
all_identifiers()
Returns an array containing the identifiers of all the available Timezones.
all_linked_zone_identifiers()
Returns an array containing the identifiers of all the available Timezones that are links to other Timezones.
all_linked_zones()
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.
get(identifier)
Returns a timezone by its identifier (e.g. "Europe/London", "America/Chicago" or "UTC").
Raises InvalidTimezoneIdentifier if the timezone couldn‘t be found.
get_proxy(identifier)
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.
new(identifier = nil)
If identifier is nil calls super(), otherwise calls get. An identfier should always be passed in when called externally.
us_zone_identifiers()
Returns all US zone identifiers. A shortcut for TZInfo::Country.get(‘US’).zone_identifiers.
us_zones()
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.
Instance Method Detail
<=>(tz)
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.
_dump(limit)
Dumps this Timezone for marshalling.
current_period()
Returns the TimezonePeriod for the current time.
current_period_and_time()
Returns the current Time and TimezonePeriod as an array. The first element is the time, the second element is the period.
current_time_and_period()
Alias for current_period_and_time
eql?(tz)
Returns true if and only if the identifier of tz is equal to the identifier of this Timezone.
friendly_identifier(skip_first_part = false)
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"
hash()
identifier()
The identifier of the timezone, e.g. "Europe/Paris".
inspect()
Returns internal object state as a programmer-readable string.
local_to_utc(local, dst = nil) {|periods| ...}
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.
name()
An alias for identifier.
now()
Returns the current time in the timezone as a Time.
period_for_local(local, dst = nil) {|results| ...}
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.
period_for_utc(utc)
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).
periods_for_local(local)
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.
strftime(format, utc = Time.now.utc)
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).
to_s()
Returns a friendlier version of the identifier.
utc_to_local(utc)
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).