timezone.rb in tzinfo-1.2.0

- old
+ new

@@ -1,27 +1,5 @@
-#--
-# Copyright (c) 2005-2013 Philip Ross
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
-#++
-
 require 'date'
 require 'set'
 require 'thread_safe'
 
 module TZInfo
@@ -325,10 +303,49 @@
     # transitions_up_to raises an ArgumentError exception.
     def transitions_up_to(utc_to, utc_from = nil)
       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
     end
     
+    # 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 Zone US/Eastern was 
+    # renamed as America/New_York. A US/Eastern Link was added in its place,
+    # linking to (and creating an alias for) for America/New_York.
+    #
+    # Links are also used for time zones that are currently identical to a full 
+    # Zone, but that are administered seperately. For example, Europe/Vatican is
+    # a Link to (and alias for) Europe/Rome.
+    #
+    # For a full Zone, canonical_zone returns self.
+    #
+    # For a Link, 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
+    # TZInfo::DataSource). Please note that some DataSource implementations may 
+    # not support distinguishing between full Zones and Links and will treat all
+    # time zones as full Zones. In this case, the canonical_zone will always 
+    # return self.
+    #
+    # There are two built-in DataSource implementations. RubyDataSource (which
+    # will be used if the tzinfo-data gem is available) supports Link zones.
+    # ZoneinfoDataSource returns Link zones as if they were full Zones. If the 
+    # canonical_zone or canonical_identifier methods are required, the 
+    # tzinfo-data gem should be installed.
+    #
+    # The TZInfo::DataSource.get method can be used to check which DataSource 
+    # implementation is being used.
+    def canonical_zone
+      raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
+    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).
     #
@@ -512,10 +529,18 @@
         
         result.to_a
       end
     end
     
+    # Returns the canonical identifier for this Timezone.
+    #
+    # This is a shortcut for calling canonical_zone.identifier. Please refer
+    # to the canonical_zone documentation for further information.
+    def canonical_identifier
+      canonical_zone.identifier
+    end
+    
     # Returns the current time in the timezone as a Time.
     def now
       utc_to_local(Time.now.utc)
     end
     
@@ -556,13 +581,16 @@
       local.strftime(format)
     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.
+    #
+    # Returns nil if tz is not comparable with Timezone instances.
     def <=>(tz)
+      return nil unless tz.is_a?(Timezone)
       identifier <=> tz.identifier
     end
-    
+
     # Returns true if and only if the identifier of tz is equal to the 
     # identifier of this Timezone.
     def eql?(tz)
       self == tz
     end