Class: TZInfo::TimezoneProxy

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Timezone`
Instance Chain: self, `Timezone`, Comparable
Inherits:	TZInfo::Timezone Object TZInfo::Timezone TZInfo::TimezoneProxy
Defined in:	lib/tzinfo/timezone_proxy.rb

Overview

A proxy class standing in for a Timezone with a given identifier. TimezoneProxy inherits from Timezone and can be treated identically to Timezone instances loaded with Timezone.get.

TimezoneProxy instances are used to avoid the performance overhead of loading time zone data into memory, for example, by Timezone.all.

The first time an attempt is made to access the data for the time zone, the real Timezone will be loaded is loaded. If the proxy's identifier was not valid, then an exception will be raised at this point.

Class Attribute Summary

`Timezone` - Inherited

.default_dst	Returns the default value of the optional `dst` parameter of the `local_time`, `local_datetime` and `local_timestamp`, `local_to_utc` and `period_for_local` methods (`nil`, `true` or `false`).
.default_dst=	Sets the default value of the optional `dst` parameter of the `local_datetime`, `local_time`, `local_timestamp`, `local_to_utc` and `period_for_local` methods.

Class Method Summary

._load(data) ⇒ TimezoneProxy

Loads a TimezoneProxy from the serialized representation returned by #_dump.
.new(identifier) ⇒ TimezoneProxy constructor

Initializes a new TimezoneProxy.

`Timezone` - Inherited

._load	Loads a `Timezone` from the serialized representation returned by #_dump.
.all	Returns an `Array` of all the available time zones.
.all_country_zone_identifiers	Returns an `Array` of the identifiers of all the time zones that are observed by at least one `Country`.
.all_country_zones	Returns an `Array` of all the time zones that are observed by at least one `Country`.
.all_data_zone_identifiers	time zones that are defined by offsets and transitions.
.all_data_zones	Returns an `Array` of all the available time zones that are defined by offsets and transitions.
.all_identifiers,
.all_linked_zone_identifiers	time zones that are defined as links to / aliases for other time zones.
.all_linked_zones	Returns an `Array` of all the available time zones that are defined as links to / aliases for other time zones.
.get	Returns a time zone by its IANA Time Zone Database identifier (e.g. `"Europe/London"` or `"America/Chicago"`).
.get_proxy	Returns a proxy for the time zone with the given identifier.
.data_source, .get_proxies

Instance Method Summary

#_dump(limit) ⇒ String

Returns a serialized representation of this TimezoneProxy.
#canonical_zone ⇒ Timezone

Returns the canonical Timezone instance for this Timezone.
#identifier ⇒ String
#period_for(time) ⇒ TimezonePeriod

Returns the TimezonePeriod that is valid at a given time.
#periods_for_local(local_time) ⇒ Array<TimezonePeriod>

Returns the set of TimezonePeriods that are valid for the given local time as an Array.
#transitions_up_to(to, from = nil) ⇒ Array<TimezoneTransition>

Returns an Array of TimezoneTransition instances representing the times where the UTC offset of the timezone changes.
#real_timezone ⇒ Timezone private

Returns the real Timezone instance being proxied.

`Timezone` - Inherited

#<=>	Compares this `Timezone` with another based on the #identifier.
#=~	Matches `regexp` against the #identifier of this `Timezone`.
#_dump	Returns a serialized representation of this `Timezone`.
#abbr	Alias for Timezone#abbreviation.
#abbreviation,
#base_utc_offset	Returns the base offset from UTC in seconds at the given time.
#canonical_identifier	Returns the canonical identifier of this time zone.
#canonical_zone	Returns the canonical `Timezone` instance for this `Timezone`.
#current_period,
#current_period_and_time	Alias for Timezone#current_time_and_period.
#current_time_and_period	Returns the current local time and `TimezonePeriod` for the time zone as an `Array`.
#dst?, #eql?,
#friendly_identifier	Returns #identifier, modified to make it more readable.
#hash, #identifier, #inspect,
#local_datetime	Creates a `DateTime` object based on the given (Gregorian calendar) date and time parameters.
#local_time	Creates a `Time` object based on the given (Gregorian calendar) date and time parameters.
#local_timestamp	Creates a `Timestamp` object based on the given (Gregorian calendar) date and time parameters.
#local_to_utc	Converts a local time for the time zone to UTC.
#name, #now,
#observed_utc_offset	Returns the observed offset from UTC in seconds at the given time.
#offsets_up_to	Returns the unique offsets used by the time zone up to a given time (`to`) as an `Array` of `TimezoneOffset` instances.
#period_for	Returns the `TimezonePeriod` that is valid at a given time.
#period_for_local	Returns the `TimezonePeriod` that is valid at the given local time.
#period_for_utc	Returns the `TimezonePeriod` that is valid at a given time.
#periods_for_local	Returns the set of `TimezonePeriod`s that are valid for the given local time as an `Array`.
#strftime	Converts a time to local time for the time zone and returns a `String` representation of the local time according to the given format.
#to_local	Converts a time to the local time for the time zone.
#to_s,
#transitions_up_to	Returns an `Array` of `TimezoneTransition` instances representing the times where the UTC offset of the timezone changes.
#utc_offset	Alias for Timezone#observed_utc_offset.
#utc_to_local	Converts a time in UTC to the local time for the time zone.
#raise_unknown_timezone	Raises an `UnknownTimezone` exception.

Constructor Details

.new(identifier) ⇒ `TimezoneProxy`

Initializes a new TimezoneProxy.

The identifier parameter is not checked when initializing the proxy. It will be validated when the real Timezone instance is loaded.

Parameters:

identifier (String) —
an IANA Time Zone Database time zone identifier.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 23


def initialize(identifier)
  super()
  @identifier = identifier
  @real_timezone = nil
end

Class Method Details

._load(data) ⇒ `TimezoneProxy`

Loads a TimezoneProxy from the serialized representation returned by #_dump. This is method is called when using Marshal.load or Marshal.restore to restore a serialized Timezone.

Parameters:

data (String) —
a serialized representation of a TimezoneProxy.

Returns:

(TimezoneProxy) —
the result of converting data back into a TimezoneProxy.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 71


def self._load(data)
  TimezoneProxy.new(data)
end

Instance Method Details

#_dump(limit) ⇒ `String`

Returns a serialized representation of this TimezoneProxy. This method is called when using Marshal.dump with an instance of TimezoneProxy.

Parameters:

limit (Integer) —
the maximum depth to dump - ignored. @return [String] a serialized representation of this TimezoneProxy.

Returns:

(String) —
a serialized representation of this TimezoneProxy.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 60


def _dump(limit)
  identifier
end

#canonical_zone ⇒ Timezone

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 US/Eastern Zone was renamed as America/New_York. A US/Eastern Link was added in its place, linking to (and creating an alias for) America/New_York.

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

For a full Zone (implemented by DataTimezone), canonical_zone returns self.

For a Link (implemented by LinkedTimezone), 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 DataSource). Some DataSource implementations may not support distinguishing between full Zones and Links and will treat all time zones as full Zones. In this case, canonical_zone will always return self.

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

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

Returns:

(Timezone) —
the canonical Timezone instance for this Timezone.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 50


def canonical_zone
  real_timezone.canonical_zone
end

#identifier ⇒ `String`

Returns:

(String) —
the identifier of the time zone, for example, "Europe/Paris".

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 30


def identifier
  @real_timezone ? @real_timezone.identifier : @identifier
end

#period_for(time) ⇒ TimezonePeriod

Returns the TimezonePeriod that is valid at a given time.

Unlike period_for_local and period_for_utc, the UTC offset of the time parameter is taken into consideration.

Parameters:

time (Object) —
a Time, DateTime or Timestamp.

Returns:

(TimezonePeriod) —
the TimezonePeriod that is valid at time.

Raises:

(ArgumentError) —
if time is nil.
(ArgumentError) —
if time is a Timestamp with an unspecified offset.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 35


def period_for(time)
  real_timezone.period_for_utc(time)
end

#periods_for_local(local_time) ⇒ `Array`<TimezonePeriod>

Returns the set of TimezonePeriods that are valid for the given local time as an Array.

The UTC offset of the local_time parameter is ignored (it is treated as a time in the time zone represented by self).

This will typically return an Array containing a single TimezonePeriod. More than one TimezonePeriod will be returned when the local time is ambiguous (for example, when daylight savings time ends). An empty Array will be returned when the local time is not valid (for example, when daylight savings time begins).

To obtain just a single TimezonePeriod in all cases, use period_for_local instead and specify how ambiguities should be resolved.

Parameters:

local_time (Object) —
a Time, DateTime or Timestamp.

Returns:

(Array<TimezonePeriod>) —
the set of TimezonePeriods that are valid at local_time.

Raises:

(ArgumentError) —
if local_time is nil.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 40


def periods_for_local(local_time)
  real_timezone.periods_for_local(local_time)
end

#real_timezone ⇒ Timezone (private)

Returns the real Timezone instance being proxied.

The real Timezone is loaded using Timezone.get on the first access.

Returns:

(Timezone) —
the real Timezone instance being proxied.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 82


def real_timezone
  # Thread-safety: It is possible that the value of @real_timezone may be
  # calculated multiple times in concurrently executing threads. It is not
  # worth the overhead of locking to ensure that @real_timezone is only
  # calculated once.
  unless @real_timezone
    result = Timezone.get(@identifier)
    return result if frozen?
    @real_timezone = result
  end

  @real_timezone
end

#transitions_up_to(to, from = nil) ⇒ `Array`<TimezoneTransition>

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

Transitions are returned up to a given time (to).

A from time may also be supplied using the from parameter. If from is not nil, only transitions from that time onwards will be returned.

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

Parameters:

to (Object) —
a Time, DateTime or Timestamp specifying the latest (exclusive) transition to return.
from (Object) (defaults to: nil) —
an optional Time, DateTime or Timestamp specifying the earliest (inclusive) transition to return.

Returns:

(Array<TimezoneTransition>) —
the transitions that are earlier than to and, if specified, at or later than from. Transitions are ordered by when they occur, from earliest to latest.

Raises:

(ArgumentError) —
if from is specified and to is not greater than from.
(ArgumentError) —
is raised if to is nil.
(ArgumentError) —
if either to or from is a Timestamp with an unspecified offset.

[ GitHub ]

# File 'lib/tzinfo/timezone_proxy.rb', line 45


def transitions_up_to(to, from = nil)
  real_timezone.transitions_up_to(to, from)
end

Class: TZInfo::TimezoneProxy

Overview

Class Attribute Summary

Timezone - Inherited

Class Method Summary

Timezone - Inherited

Instance Method Summary

Timezone - Inherited

Constructor Details

.new(identifier) ⇒ TimezoneProxy

Class Method Details

._load(data) ⇒ TimezoneProxy

Instance Method Details

#_dump(limit) ⇒ String

#canonical_zone ⇒ Timezone

#identifier ⇒ String

#period_for(time) ⇒ TimezonePeriod

#periods_for_local(local_time) ⇒ Array<TimezonePeriod>

#real_timezone ⇒ Timezone (private)

#transitions_up_to(to, from = nil) ⇒ Array<TimezoneTransition>

`Timezone` - Inherited

`Timezone` - Inherited

`Timezone` - Inherited

.new(identifier) ⇒ `TimezoneProxy`

._load(data) ⇒ `TimezoneProxy`

#_dump(limit) ⇒ `String`

#identifier ⇒ `String`

#periods_for_local(local_time) ⇒ `Array`<TimezonePeriod>

#transitions_up_to(to, from = nil) ⇒ `Array`<TimezoneTransition>