Method: TZInfo::Timezone#canonical_zone

Defined in:
lib/tzinfo/timezone.rb

#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 #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:



412
413
414
 
# File 'lib/tzinfo/timezone.rb', line 412

def canonical_zone
  raise_unknown_timezone
end