Class: TZInfo::TimezoneProxy

Inherits:
Timezone show all
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 TZInfo::Timezone.get.

TimezoneProxy instances are used to avoid the performance overhead of loading time zone data into memory, for example, by TZInfo::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 Method Summary collapse

Instance Method Summary collapse

Methods inherited from Timezone

#<=>, #=~, #abbreviation, all, all_country_zone_identifiers, all_country_zones, all_data_zone_identifiers, all_data_zones, all_identifiers, all_linked_zone_identifiers, all_linked_zones, #base_utc_offset, #canonical_identifier, #current_period, #current_time_and_period, default_dst, default_dst=, #dst?, #eql?, #friendly_identifier, get, get_proxy, #hash, #inspect, #local_datetime, #local_time, #local_timestamp, #local_to_utc, #name, #now, #observed_utc_offset, #offsets_up_to, #period_for_local, #period_for_utc, #strftime, #to_local, #to_s, #utc_to_local

Constructor Details

#initialize(identifier) ⇒ TimezoneProxy

Initializes a new TZInfo::TimezoneProxy.

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

Parameters:

  • identifier (String) —

    an IANA Time Zone Database time zone identifier.



23
24
25
26
27
 
# 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 TZInfo::TimezoneProxy from the serialized representation returned by #_dump. This is method is called when using Marshal.load or Marshal.restore to restore a serialized TZInfo::Timezone.

Parameters:

Returns:



71
72
73
 
# 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 TZInfo::TimezoneProxy. This method is called when using Marshal.dump with an instance of TZInfo::TimezoneProxy.

Parameters:

  • limit (Integer) —

    the maximum depth to dump - ignored. @return [String] a serialized representation of this TZInfo::TimezoneProxy.

Returns:



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

def _dump(limit)
  identifier
end

#canonical_zone ⇒ Timezone

Returns the canonical TZInfo::Timezone instance for this TZInfo::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 TZInfo::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 TZInfo::Timezone#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:



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

def canonical_zone
  real_timezone.canonical_zone
end

#identifier ⇒ String

Returns the identifier of the time zone, for example, "Europe/Paris".

Returns:

  • (String) —

    the identifier of the time zone, for example, "Europe/Paris".



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

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

#period_for(time) ⇒ TimezonePeriod

Returns the TZInfo::TimezonePeriod that is valid at a given time.

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if time is nil.

  • (ArgumentError) —

    if time is a TZInfo::Timestamp with an unspecified offset.



35
36
37
 
# 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 TZInfo::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 TZInfo::TimezonePeriod. More than one TZInfo::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 TZInfo::TimezonePeriod in all cases, use TZInfo::Timezone#period_for_local instead and specify how ambiguities should be resolved.

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if local_time is nil.



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

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

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

Returns an Array of TZInfo::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 TZInfo::Timestamp specifying the latest (exclusive) transition to return.

  • from (Object) (defaults to: nil) —

    an optional Time, DateTime or TZInfo::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 TZInfo::Timestamp with an unspecified offset.



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

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