activesupport 3.0.0.beta4 → 3.0.pre

data/lib/active_support/vendor/tzinfo-0.3.13/lib/tzinfo/ruby_core_support.rb

@@ -0,0 +1,56 @@
+#--
+# Copyright (c) 2008 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 'rational'
+
+module TZInfo
+  
+  # Methods to support different versions of Ruby.
+  module RubyCoreSupport #:nodoc:
+  
+    # Use Rational.new! for performance reasons in Ruby 1.8.
+    # This has been removed from 1.9, but Rational performs better.        
+    if Rational.respond_to? :new!
+      def self.rational_new!(numerator, denominator = 1)
+        Rational.new!(numerator, denominator)
+      end
+    else
+      def self.rational_new!(numerator, denominator = 1)
+        Rational(numerator, denominator)
+      end
+    end
+    
+    # Ruby 1.8.6 introduced new! and deprecated new0.
+    # Ruby 1.9.0 removed new0.
+    # We still need to support new0 for older versions of Ruby.
+    if DateTime.respond_to? :new!
+      def self.datetime_new!(ajd = 0, of = 0, sg = Date::ITALY)
+        DateTime.new!(ajd, of, sg)
+      end
+    else
+      def self.datetime_new!(ajd = 0, of = 0, sg = Date::ITALY)
+        DateTime.new0(ajd, of, sg)
+      end
+    end
+  end
+end

data/lib/active_support/vendor/tzinfo-0.3.13/lib/tzinfo/time_or_datetime.rb

@@ -0,0 +1,292 @@
+#--
+# Copyright (c) 2006 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 'time'
+require 'tzinfo/offset_rationals'
+
+module TZInfo
+  # Used by TZInfo internally to represent either a Time, DateTime or integer
+  # timestamp (seconds since 1970-01-01 00:00:00).
+  class TimeOrDateTime #:nodoc:
+    include Comparable
+    
+    # Constructs a new TimeOrDateTime. timeOrDateTime can be a Time, DateTime
+    # or an integer. If using a Time or DateTime, any time zone information is 
+    # ignored.
+    def initialize(timeOrDateTime)
+      @time = nil
+      @datetime = nil
+      @timestamp = nil
+      
+      if timeOrDateTime.is_a?(Time)
+        @time = timeOrDateTime        
+        @time = Time.utc(@time.year, @time.mon, @time.mday, @time.hour, @time.min, @time.sec) unless @time.zone == 'UTC'        
+        @orig = @time
+      elsif timeOrDateTime.is_a?(DateTime)
+        @datetime = timeOrDateTime
+        @datetime = @datetime.new_offset(0) unless @datetime.offset == 0
+        @orig = @datetime
+      else
+        @timestamp = timeOrDateTime.to_i
+        @orig = @timestamp
+      end
+    end
+    
+    # Returns the time as a Time.
+    def to_time
+      unless @time        
+        if @timestamp 
+          @time = Time.at(@timestamp).utc
+        else
+          @time = Time.utc(year, mon, mday, hour, min, sec)
+        end
+      end
+      
+      @time      
+    end
+    
+    # Returns the time as a DateTime.
+    def to_datetime
+      unless @datetime
+        @datetime = DateTime.new(year, mon, mday, hour, min, sec)
+      end
+      
+      @datetime
+    end
+    
+    # Returns the time as an integer timestamp.
+    def to_i
+      unless @timestamp
+        @timestamp = to_time.to_i
+      end
+      
+      @timestamp
+    end
+    
+    # Returns the time as the original time passed to new.
+    def to_orig
+      @orig
+    end
+    
+    # Returns a string representation of the TimeOrDateTime.
+    def to_s
+      if @orig.is_a?(Time)
+        "Time: #{@orig.to_s}"
+      elsif @orig.is_a?(DateTime)
+        "DateTime: #{@orig.to_s}"
+      else
+        "Timestamp: #{@orig.to_s}"
+      end
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #{@orig.inspect}>"
+    end
+    
+    # Returns the year.
+    def year
+      if @time
+        @time.year
+      elsif @datetime
+        @datetime.year
+      else
+        to_time.year
+      end
+    end
+    
+    # Returns the month of the year (1..12).
+    def mon
+      if @time
+        @time.mon
+      elsif @datetime
+        @datetime.mon
+      else
+        to_time.mon
+      end
+    end
+    alias :month :mon
+    
+    # Returns the day of the month (1..n).
+    def mday
+      if @time
+        @time.mday
+      elsif @datetime
+        @datetime.mday
+      else
+        to_time.mday
+      end
+    end
+    alias :day :mday
+    
+    # Returns the hour of the day (0..23).
+    def hour
+      if @time
+        @time.hour
+      elsif @datetime
+        @datetime.hour
+      else
+        to_time.hour
+      end
+    end
+    
+    # Returns the minute of the hour (0..59).
+    def min
+      if @time
+        @time.min
+      elsif @datetime
+        @datetime.min
+      else
+        to_time.min
+      end
+    end
+    
+    # Returns the second of the minute (0..60). (60 for a leap second).
+    def sec
+      if @time
+        @time.sec
+      elsif @datetime
+        @datetime.sec
+      else
+        to_time.sec
+      end
+    end
+    
+    # Compares this TimeOrDateTime with another Time, DateTime, integer
+    # timestamp or TimeOrDateTime. Returns -1, 0 or +1 depending whether the 
+    # receiver is less than, equal to, or greater than timeOrDateTime.
+    #
+    # Milliseconds and smaller units are ignored in the comparison.
+    def <=>(timeOrDateTime)
+      if timeOrDateTime.is_a?(TimeOrDateTime)            
+        orig = timeOrDateTime.to_orig
+        
+        if @orig.is_a?(DateTime) || orig.is_a?(DateTime)
+          # If either is a DateTime, assume it is there for a reason 
+          # (i.e. for range).
+          to_datetime <=> timeOrDateTime.to_datetime
+        elsif orig.is_a?(Time)
+          to_time <=> timeOrDateTime.to_time
+        else
+          to_i <=> timeOrDateTime.to_i
+        end        
+      elsif @orig.is_a?(DateTime) || timeOrDateTime.is_a?(DateTime)
+        # If either is a DateTime, assume it is there for a reason 
+        # (i.e. for range).        
+        to_datetime <=> TimeOrDateTime.wrap(timeOrDateTime).to_datetime
+      elsif timeOrDateTime.is_a?(Time)
+        to_time <=> timeOrDateTime
+      else
+        to_i <=> timeOrDateTime.to_i
+      end
+    end
+    
+    # Adds a number of seconds to the TimeOrDateTime. Returns a new 
+    # TimeOrDateTime, preserving what the original constructed type was.
+    # If the original type is a Time and the resulting calculation goes out of
+    # range for Times, then an exception will be raised by the Time class.
+    def +(seconds)
+      if seconds == 0
+        self
+      else
+        if @orig.is_a?(DateTime)
+          TimeOrDateTime.new(@orig + OffsetRationals.rational_for_offset(seconds))
+        else
+          # + defined for Time and integer timestamps
+          TimeOrDateTime.new(@orig + seconds)
+        end
+      end
+    end
+    
+    # Subtracts a number of seconds from the TimeOrDateTime. Returns a new 
+    # TimeOrDateTime, preserving what the original constructed type was.
+    # If the original type is a Time and the resulting calculation goes out of
+    # range for Times, then an exception will be raised by the Time class.
+    def -(seconds)
+      self + (-seconds)
+    end
+   
+    # Similar to the + operator, but for cases where adding would cause a 
+    # timestamp or time to go out of the allowed range, converts to a DateTime
+    # based TimeOrDateTime.
+    def add_with_convert(seconds)
+      if seconds == 0
+        self
+      else
+        if @orig.is_a?(DateTime)
+          TimeOrDateTime.new(@orig + OffsetRationals.rational_for_offset(seconds))
+        else
+          # A Time or timestamp.
+          result = to_i + seconds
+          
+          if result < 0 || result > 2147483647
+            result = TimeOrDateTime.new(to_datetime + OffsetRationals.rational_for_offset(seconds))
+          else
+            result = TimeOrDateTime.new(@orig + seconds)
+          end
+        end
+      end
+    end
+    
+    # Returns true if todt represents the same time and was originally 
+    # constructed with the same type (DateTime, Time or timestamp) as this 
+    # TimeOrDateTime.
+    def eql?(todt)
+      todt.respond_to?(:to_orig) && to_orig.eql?(todt.to_orig)      
+    end
+    
+    # Returns a hash of this TimeOrDateTime.
+    def hash
+      @orig.hash
+    end
+    
+    # If no block is given, returns a TimeOrDateTime wrapping the given 
+    # timeOrDateTime. If a block is specified, a TimeOrDateTime is constructed
+    # and passed to the block. The result of the block must be a TimeOrDateTime.
+    # to_orig will be called on the result and the result of to_orig will be
+    # returned.
+    #
+    # timeOrDateTime can be a Time, DateTime, integer timestamp or TimeOrDateTime.
+    # If a TimeOrDateTime is passed in, no new TimeOrDateTime will be constructed,
+    # the passed in value will be used.
+    def self.wrap(timeOrDateTime)      
+      t = timeOrDateTime.is_a?(TimeOrDateTime) ? timeOrDateTime : TimeOrDateTime.new(timeOrDateTime)        
+      
+      if block_given?
+        t = yield t
+        
+        if timeOrDateTime.is_a?(TimeOrDateTime)
+          t          
+        elsif timeOrDateTime.is_a?(Time)
+          t.to_time
+        elsif timeOrDateTime.is_a?(DateTime)
+          t.to_datetime
+        else
+          t.to_i
+        end        
+      else
+        t
+      end
+    end
+  end
+end

data/lib/active_support/vendor/tzinfo-0.3.13/lib/tzinfo/timezone.rb

@@ -0,0 +1,508 @@
+#--
+# Copyright (c) 2005-2006 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 'tzinfo/country'
+require 'tzinfo/time_or_datetime'
+require 'tzinfo/timezone_period'
+
+module TZInfo
+  # Indicate a specified time in a local timezone has more than one
+  # possible time in UTC. This happens when switching from daylight savings time 
+  # to normal time where the clocks are rolled back. Thrown by period_for_local
+  # and local_to_utc when using an ambiguous time and not specifying any 
+  # means to resolve the ambiguity.
+  class AmbiguousTime < StandardError
+  end
+  
+  # Thrown to indicate that no TimezonePeriod matching a given time could be found.
+  class PeriodNotFound < StandardError
+  end
+  
+  # Thrown by Timezone#get if the identifier given is not valid.
+  class InvalidTimezoneIdentifier < StandardError
+  end
+  
+  # Thrown if an attempt is made to use a timezone created with Timezone.new(nil).
+  class UnknownTimezone < StandardError
+  end
+  
+  # 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 http://www.twinsun.com/tz/tz-link.htm)
+  class Timezone
+    include Comparable
+    
+    # Cache of loaded zones by identifier to avoid using require if a zone
+    # has already been loaded.
+    @@loaded_zones = {}
+    
+    # Whether the timezones index has been loaded yet.
+    @@index_loaded = false
+    
+    # Returns a timezone by its identifier (e.g. "Europe/London", 
+    # "America/Chicago" or "UTC").
+    #
+    # Raises InvalidTimezoneIdentifier if the timezone couldn't be found.
+    def self.get(identifier)
+      instance = @@loaded_zones[identifier]
+      unless instance  
+        raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-z0-9\+\-_]+(\/[A-z0-9\+\-_]+)*$/
+        identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__')
+        begin
+          # Use a temporary variable to avoid an rdoc warning
+          file = "tzinfo/definitions/#{identifier}".untaint
+          require file
+          
+          m = Definitions
+          identifier.split(/\//).each {|part|
+            m = m.const_get(part)
+          }
+          
+          info = m.get
+          
+          # Could make Timezone subclasses register an interest in an info
+          # type. Since there are currently only two however, there isn't
+          # much point.
+          if info.kind_of?(DataTimezoneInfo)
+            instance = DataTimezone.new(info)
+          elsif info.kind_of?(LinkedTimezoneInfo)
+            instance = LinkedTimezone.new(info)
+          else
+            raise InvalidTimezoneIdentifier, "No handler for info type #{info.class}"
+          end
+          
+          @@loaded_zones[instance.identifier] = instance         
+        rescue LoadError, NameError => e
+          raise InvalidTimezoneIdentifier, e.message
+        end
+      end
+      
+      instance
+    end
+    
+    # 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. 
+    def self.get_proxy(identifier)
+      TimezoneProxy.new(identifier)
+    end
+    
+    # If identifier is nil calls super(), otherwise calls get. An identfier 
+    # should always be passed in when called externally.
+    def self.new(identifier = nil)
+      if identifier        
+        get(identifier)
+      else
+        super()
+      end
+    end
+    
+    # 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.
+    def self.all
+      get_proxies(all_identifiers)
+    end
+    
+    # Returns an array containing the identifiers of all the available 
+    # Timezones.
+    def self.all_identifiers
+      load_index
+      Indexes::Timezones.timezones
+    end
+    
+    # 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.
+    def self.all_data_zones
+      get_proxies(all_data_zone_identifiers)
+    end
+    
+    # Returns an array containing the identifiers of all the available 
+    # Timezones that are based on data (are not links to other Timezones)..
+    def self.all_data_zone_identifiers
+      load_index
+      Indexes::Timezones.data_timezones
+    end
+    
+    # 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.
+    def self.all_linked_zones
+      get_proxies(all_linked_zone_identifiers)      
+    end
+    
+    # Returns an array containing the identifiers of all the available 
+    # Timezones that are links to other Timezones.
+    def self.all_linked_zone_identifiers
+      load_index
+      Indexes::Timezones.linked_timezones
+    end
+    
+    # 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.        
+    def self.all_country_zones
+      Country.all_codes.inject([]) {|zones,country|
+        zones += Country.get(country).zones
+      }
+    end
+    
+    # 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.
+    def self.all_country_zone_identifiers
+      Country.all_codes.inject([]) {|zones,country|
+        zones += Country.get(country).zone_identifiers
+      }
+    end
+    
+    # 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.
+    def self.us_zones
+      Country.get('US').zones
+    end
+    
+    # Returns all US zone identifiers. A shortcut for 
+    # TZInfo::Country.get('US').zone_identifiers.
+    def self.us_zone_identifiers
+      Country.get('US').zone_identifiers
+    end
+    
+    # The identifier of the timezone, e.g. "Europe/Paris".
+    def identifier
+      raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
+    end
+    
+    # An alias for identifier.
+    def name
+      # Don't use alias, as identifier gets overridden.
+      identifier
+    end
+    
+    # Returns a friendlier version of the identifier.
+    def to_s
+      friendly_identifier
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #{identifier}>"
+    end
+    
+    # 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"           
+    def friendly_identifier(skip_first_part = false)
+      parts = identifier.split('/')
+      if parts.empty?
+        # shouldn't happen
+        identifier
+      elsif parts.length == 1        
+        parts[0]
+      else
+        if skip_first_part
+          result = ''
+        else
+          result = parts[0] + ' - '
+        end
+        
+        parts[1, parts.length - 1].reverse_each {|part|
+          part.gsub!(/_/, ' ')
+          
+          if part.index(/[a-z]/)
+            # Missing a space if a lower case followed by an upper case and the
+            # name isn't McXxxx.
+            part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2')
+            part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2')
+            
+            # Missing an apostrophe if two consecutive upper case characters.
+            part.gsub!(/([A-Z])([A-Z])/, '\1\'\2')
+          end
+          
+          result << part
+          result << ', '
+        }
+        
+        result.slice!(result.length - 2, 2)
+        result
+      end
+    end
+    
+    # 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).        
+    def period_for_utc(utc)            
+      raise UnknownTimezone, 'TZInfo::Timezone constructed directly'      
+    end
+    
+    # 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.
+    def periods_for_local(local)
+      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).
+    #
+    # 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.
+    def period_for_local(local, dst = nil)            
+      results = periods_for_local(local)
+      
+      if results.empty?
+        raise PeriodNotFound
+      elsif results.size < 2
+        results.first
+      else
+        # ambiguous result try to resolve
+        
+        if !dst.nil?
+          matches = results.find_all {|period| period.dst? == dst}
+          results = matches if !matches.empty?            
+        end
+        
+        if results.size < 2
+          results.first
+        else
+          # still ambiguous, try the block
+                    
+          if block_given?
+            results = yield results
+          end
+          
+          if results.is_a?(TimezonePeriod)
+            results
+          elsif results && results.size == 1
+            results.first
+          else          
+            raise AmbiguousTime, "#{local} is an ambiguous local time."
+          end
+        end
+      end      
+    end
+    
+    # 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).
+    def utc_to_local(utc)
+      TimeOrDateTime.wrap(utc) {|wrapped|
+        period_for_utc(wrapped).to_local(wrapped)
+      }
+    end
+    
+    # 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.
+    def local_to_utc(local, dst = nil)
+      TimeOrDateTime.wrap(local) {|wrapped|
+        if block_given?
+          period = period_for_local(wrapped, dst) {|periods| yield periods }
+        else
+          period = period_for_local(wrapped, dst)
+        end
+        
+        period.to_utc(wrapped)
+      }
+    end
+    
+    # Returns the current time in the timezone as a Time.
+    def now
+      utc_to_local(Time.now.utc)
+    end
+    
+    # Returns the TimezonePeriod for the current time. 
+    def current_period
+      period_for_utc(Time.now.utc)
+    end
+    
+    # Returns the current Time and TimezonePeriod as an array. The first element
+    # is the time, the second element is the period.
+    def current_period_and_time
+      utc = Time.now.utc
+      period = period_for_utc(utc)
+      [period.to_local(utc), period]
+    end
+    
+    alias :current_time_and_period :current_period_and_time
+
+    # 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).        
+    def strftime(format, utc = Time.now.utc)      
+      period = period_for_utc(utc)
+      local = period.to_local(utc)      
+      local = Time.at(local).utc unless local.kind_of?(Time) || local.kind_of?(DateTime)
+      abbreviation = period.abbreviation.to_s.gsub(/%/, '%%')
+      
+      format = format.gsub(/(.?)%Z/) do
+        if $1 == '%'
+          # return %%Z so the real strftime treats it as a literal %Z too
+          '%%Z'
+        else
+          "#$1#{abbreviation}"
+        end
+      end
+      
+      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.
+    def <=>(tz)
+      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
+    
+    # Returns a hash of this Timezone.
+    def hash
+      identifier.hash
+    end
+    
+    # Dumps this Timezone for marshalling.
+    def _dump(limit)
+      identifier
+    end
+    
+    # Loads a marshalled Timezone.
+    def self._load(data)
+      Timezone.get(data)
+    end
+    
+    private
+      # Loads in the index of timezones if it hasn't already been loaded.
+      def self.load_index
+        unless @@index_loaded
+          require 'tzinfo/indexes/timezones'
+          @@index_loaded = true
+        end        
+      end
+      
+      # Returns an array of proxies corresponding to the given array of 
+      # identifiers.
+      def self.get_proxies(identifiers)
+        identifiers.collect {|identifier| get_proxy(identifier)}
+      end
+  end        
+end