Introduce ActiveSupport::TimeWithZone, for wrapping Time instances with a TimeZone. Introduce instance methods to Time for creating TimeWithZone instances, and class methods for managing a global time zone

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8696 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

5 files changed, 230 insertions, 0 deletions

diff --git a/activesupport/lib/active_support.rb b/activesupport/lib/active_support.rb
index 7a0476b729..4d2f873a8d 100644
--- a/activesupport/lib/active_support.rb
+++ b/activesupport/lib/active_support.rb
@@ -50,3 +50,5 @@ require 'active_support/json'
 require 'active_support/multibyte'
 
 require 'active_support/base64'
+
+require 'active_support/time_with_zone'
diff --git a/activesupport/lib/active_support/core_ext/date_time.rb b/activesupport/lib/active_support/core_ext/date_time.rb
index 1d711de70b..66a93eac43 100644
--- a/activesupport/lib/active_support/core_ext/date_time.rb
+++ b/activesupport/lib/active_support/core_ext/date_time.rb
@@ -1,10 +1,12 @@
 require 'date'
 require 'active_support/core_ext/time/behavior'
+require 'active_support/core_ext/time/zones'
 require 'active_support/core_ext/date_time/calculations'
 require 'active_support/core_ext/date_time/conversions'
 
 class DateTime
   include ActiveSupport::CoreExtensions::Time::Behavior
+  include ActiveSupport::CoreExtensions::Time::Zones
   include ActiveSupport::CoreExtensions::DateTime::Calculations
   include ActiveSupport::CoreExtensions::DateTime::Conversions
 end
diff --git a/activesupport/lib/active_support/core_ext/time.rb b/activesupport/lib/active_support/core_ext/time.rb
index d87c4ec65a..ea50511a96 100644
--- a/activesupport/lib/active_support/core_ext/time.rb
+++ b/activesupport/lib/active_support/core_ext/time.rb
@@ -11,9 +11,11 @@ end
 require 'active_support/core_ext/time/behavior'
 require 'active_support/core_ext/time/calculations'
 require 'active_support/core_ext/time/conversions'
+require 'active_support/core_ext/time/zones'
 
 class Time#:nodoc:
   include ActiveSupport::CoreExtensions::Time::Behavior
   include ActiveSupport::CoreExtensions::Time::Calculations
   include ActiveSupport::CoreExtensions::Time::Conversions
+  include ActiveSupport::CoreExtensions::Time::Zones
 end
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
new file mode 100644
index 0000000000..563d522d9a
--- /dev/null
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -0,0 +1,68 @@
+module ActiveSupport #:nodoc:
+  module CoreExtensions #:nodoc:
+    module Time #:nodoc:
+      # Methods for creating TimeWithZone objects from Time instances
+      module Zones
+        
+        def self.included(base) #:nodoc:
+          base.extend(ClassMethods) if base == ::Time # i.e., don't include class methods in DateTime
+        end
+        
+        module ClassMethods
+          attr_reader :zone
+
+          # Sets a global default time zone, separate from the system time zone in ENV['TZ']. 
+          # Accepts either a Rails TimeZone object, a string that identifies a 
+          # Rails TimeZone object (e.g., "Central Time (US & Canada)"), or a TZInfo::Timezone object
+          #
+          # Any Time or DateTime object can use this default time zone, via #in_current_time_zone.
+          # Example:
+          #
+          #   Time.zone = 'Hawaii'                  # => 'Hawaii'
+          #   Time.utc(2000).in_current_time_zone   # => Fri, 31 Dec 1999 14:00:00 HST -10:00
+          def zone=(zone)
+            @zone = get_zone(zone)
+          end
+          
+          def zone_reset!
+            @zone = nil
+          end
+          
+          def get_zone(zone)
+            ::String === zone || ::Numeric === zone ? TimeZone[zone] : zone
+          end
+        end
+        
+        # Gives the corresponding time in the supplied zone. self is assumed to be in UTC regardless of constructor.
+        #
+        # Examples:
+        #
+        #   t = Time.utc(2000)        # => Sat Jan 01 00:00:00 UTC 2000
+        #   t.in_time_zone('Alaska')  # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
+        #   t.in_time_zone('Hawaii')  # => Fri, 31 Dec 1999 14:00:00 HST -10:00
+        def in_time_zone(zone)
+          ActiveSupport::TimeWithZone.new(self, ::Time.get_zone(zone))
+        end
+
+        # Returns the simultaneous time in Time.zone
+        def in_current_time_zone
+          in_time_zone(::Time.zone)
+        end
+
+        # Replaces the existing zone; leaves time value intact. Examples:
+        #
+        #   t = Time.utc(2000)            # => Sat Jan 01 00:00:00 UTC 2000
+        #   t.change_time_zone('Alaska')  # => Sat, 01 Jan 2000 00:00:00 AKST -09:00
+        #   t.change_time_zone('Hawaii')  # => Sat, 01 Jan 2000 00:00:00 HST -10:00
+        def change_time_zone(zone)
+          ActiveSupport::TimeWithZone.new(nil, ::Time.get_zone(zone), self)
+        end
+
+        # Replaces the existing zone to Time.zone; leaves time value intact
+        def change_time_zone_to_current
+          change_time_zone(::Time.zone)
+        end
+      end
+    end
+  end
+end
\ No newline at end of file
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
new file mode 100644
index 0000000000..dcd55ae93d
--- /dev/null
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -0,0 +1,156 @@
+module ActiveSupport
+  # A Time-like class that can represent a time in any time zone. Necessary because standard Ruby Time instances are 
+  # limited to UTC and the system's ENV['TZ'] zone
+  class TimeWithZone
+    include Comparable
+    attr_reader :time_zone
+  
+    def initialize(utc_time, time_zone = nil, local_time = nil)
+      @utc = utc_time
+      @time = local_time
+      @time_zone = time_zone
+    end
+  
+    # Returns a Time instance that represents the time in time_zone
+    def time
+      @time ||= utc? ? @utc : time_zone.utc_to_local(@utc)
+    end
+
+    # Returns a Time instance that represents the time in UTC
+    def utc
+      @utc ||= utc? ? @time : time_zone.local_to_utc(@time)
+    end
+    alias_method :comparable_time, :utc
+  
+    # Returns the underlying TZInfo::TimezonePeriod for the local time
+    def period
+      @period ||= get_period_for_local
+    end
+
+    # Returns the simultaneous time in the specified zone
+    def in_time_zone(new_zone)
+      utc.in_time_zone(new_zone)
+    end
+  
+    # Returns the simultaneous time in Time.zone
+    def in_current_time_zone
+      utc.in_current_time_zone
+    end
+  
+    # Changes the time zone without converting the time
+    def change_time_zone(new_zone)
+      time.change_time_zone(new_zone)
+    end
+  
+    # Changes the time zone to Time.zone without converting the time
+    def change_time_zone_to_current
+      time.change_time_zone_to_current
+    end
+  
+    # Returns a Time.local() instance of the simultaneous time in your system's ENV['TZ'] zone
+    def localtime
+      utc.dup.localtime # use #dup because Time#localtime is destructive
+    end
+  
+    def dst?
+      utc? ? false : period.dst?
+    end
+  
+    # The TimeZone class has no zone for UTC, so this class uses the absence of a time zone to indicate UTC
+    def utc?
+      !time_zone
+    end
+  
+    def utc_offset
+      utc? ? 0 : period.utc_total_offset
+    end
+  
+    def formatted_offset(colon = true, alternate_utc_string = nil)
+      utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
+    end
+  
+    # Time uses #zone to display the time zone abbreviation, so we're duck-typing it
+    def zone
+      utc? ? 'UTC' : period.abbreviation.to_s
+    end
+  
+    def inspect
+      "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
+    end
+
+    def xmlschema
+      "#{time.strftime("%Y-%m-%dT%H:%M:%S")}#{formatted_offset(true, 'Z')}"
+    end
+  
+    def to_json(options = nil)
+      %("#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}")
+    end
+  
+    # :db format outputs time in UTC; all others output time in local. Uses TimeWithZone's strftime, so %Z and %z work correctly
+    def to_s(format = :default) 
+      return utc.to_s(format) if format == :db
+      if formatter = ::Time::DATE_FORMATS[format]
+        formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
+      else
+        "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby 1.9 Time#to_s format
+      end
+    end
+    
+    # Replaces %Z and %z directives with #zone and #formatted_offset, respectively, before passing to 
+    # Time#strftime, so that zone information is correct
+    def strftime(format)
+      format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false))
+      time.strftime(format)
+    end
+  
+    # Use the time in UTC for comparisons
+    def <=>(other)
+      other = other.comparable_time if other.respond_to?(:comparable_time) # to coerce time from TimeWithZone
+      utc <=> other
+    end
+  
+    # A TimeProxy acts like a Time, so just return self
+    def to_time
+      self
+    end
+    
+    # so that self acts_like?(:time)
+    def acts_like_time?
+      true
+    end
+  
+    # Say we're a Time to thwart type checking
+    def is_a?(klass)
+      klass == ::Time || super
+    end
+    alias_method :kind_of?, :is_a?
+  
+    # Neuter freeze because freezing can cause problems with lazy loading of attributes
+    def freeze
+      self
+    end
+  
+    # Ensure proxy class responds to all methods that underlying time instance responds to
+    def respond_to?(sym)
+      super || time.respond_to?(sym)
+    end
+  
+    # Send the missing method to time instance, and wrap result in a new TimeWithZone with the existing time_zone
+    def method_missing(sym, *args, &block)
+      result = time.__send__(sym, *args, &block)
+      result = result.change_time_zone(time_zone) if result.acts_like?(:time)
+      result
+    end
+  
+    private
+      def get_period_for_local
+        t = time
+        begin
+          time_zone.period_for_local(t, true)
+        rescue ::TZInfo::PeriodNotFound # failover logic from TzTime
+          t -= 1.hour
+          retry
+        end
+      end
+  end
+end