activesupport 5.0.0 → 6.1.0

data/lib/active_support/testing/time_helpers.rb

@@ -1,48 +1,80 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/redefine_method"
+require "active_support/core_ext/time/calculations"
+require "concurrent/map"
+
 module ActiveSupport
   module Testing
+    # Manages stubs for TimeHelpers
     class SimpleStubs # :nodoc:
       Stub = Struct.new(:object, :method_name, :original_method)
 
       def initialize
-        @stubs = {}
+        @stubs = Concurrent::Map.new { |h, k| h[k] = {} }
       end
 
-      def stub_object(object, method_name, return_value)
-        key = [object.object_id, method_name]
-
-        if stub = @stubs[key]
+      # Stubs object.method_name with the given block
+      # If the method is already stubbed, remove that stub
+      # so that removing this stub will restore the original implementation.
+      #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
+      #   target = Time.zone.local(2004, 11, 24, 1, 4, 44)
+      #   simple_stubs.stub_object(Time, :now) { at(target.to_i) }
+      #   Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
+      def stub_object(object, method_name, &block)
+        if stub = stubbing(object, method_name)
           unstub_object(stub)
         end
 
         new_name = "__simple_stub__#{method_name}"
 
-        @stubs[key] = Stub.new(object, method_name, new_name)
+        @stubs[object.object_id][method_name] = Stub.new(object, method_name, new_name)
 
-        object.singleton_class.send :alias_method, new_name, method_name
-        object.define_singleton_method(method_name) { return_value }
+        object.singleton_class.alias_method new_name, method_name
+        object.define_singleton_method(method_name, &block)
       end
 
+      # Remove all object-method stubs held by this instance
       def unstub_all!
-        @stubs.each_value do |stub|
-          unstub_object(stub)
+        @stubs.each_value do |object_stubs|
+          object_stubs.each_value do |stub|
+            unstub_object(stub)
+          end
         end
-        @stubs = {}
+        @stubs.clear
       end
 
-      private
+      # Returns the Stub for object#method_name
+      # (nil if it is not stubbed)
+      def stubbing(object, method_name)
+        @stubs[object.object_id][method_name]
+      end
+
+      # Returns true if any stubs are set, false if there are none
+      def stubbed?
+        !@stubs.empty?
+      end
 
+      private
+        # Restores the original object.method described by the Stub
         def unstub_object(stub)
           singleton_class = stub.object.singleton_class
-          singleton_class.send :undef_method, stub.method_name
-          singleton_class.send :alias_method, stub.method_name, stub.original_method
-          singleton_class.send :undef_method, stub.original_method
+          singleton_class.silence_redefinition_of_method stub.method_name
+          singleton_class.alias_method stub.method_name, stub.original_method
+          singleton_class.undef_method stub.original_method
         end
     end
 
     # Contains helpers that help you test passage of time.
     module TimeHelpers
+      def after_teardown
+        travel_back
+        super
+      end
+
       # Changes current time to the time in the future or in the past by a given time difference by
-      # stubbing +Time.now+, +Date.today+, and +DateTime.now+.
+      # stubbing +Time.now+, +Date.today+, and +DateTime.now+. The stubs are automatically removed
+      # at the end of the test.
       #
       #   Time.current     # => Sat, 09 Nov 2013 15:34:49 EST -05:00
       #   travel 1.day
@@ -64,9 +96,10 @@ module ActiveSupport
 
       # Changes current time to the given time by stubbing +Time.now+,
       # +Date.today+, and +DateTime.now+ to return the time or date passed into this method.
+      # The stubs are automatically removed at the end of the test.
       #
       #   Time.current     # => Sat, 09 Nov 2013 15:34:49 EST -05:00
-      #   travel_to Time.new(2004, 11, 24, 01, 04, 44)
+      #   travel_to Time.zone.local(2004, 11, 24, 1, 4, 44)
       #   Time.current     # => Wed, 24 Nov 2004 01:04:44 EST -05:00
       #   Date.current     # => Wed, 24 Nov 2004
       #   DateTime.current # => Wed, 24 Nov 2004 01:04:44 -0500
@@ -88,20 +121,48 @@ module ActiveSupport
       # state at the end of the block:
       #
       #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
-      #   travel_to Time.new(2004, 11, 24, 01, 04, 44) do
+      #   travel_to Time.zone.local(2004, 11, 24, 1, 4, 44) do
       #     Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
       #   end
       #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
       def travel_to(date_or_time)
+        if block_given? && simple_stubs.stubbing(Time, :now)
+          travel_to_nested_block_call = <<~MSG
+
+      Calling `travel_to` with a block, when we have previously already made a call to `travel_to`, can lead to confusing time stubbing.
+
+      Instead of:
+
+         travel_to 2.days.from_now do
+           # 2 days from today
+           travel_to 3.days.from_now do
+             # 5 days from today
+           end
+         end
+
+      preferred way to achieve above is:
+
+         travel 2.days do
+           # 2 days from today
+         end
+
+         travel 5.days do
+           # 5 days from today
+         end
+
+          MSG
+          raise travel_to_nested_block_call
+        end
+
         if date_or_time.is_a?(Date) && !date_or_time.is_a?(DateTime)
           now = date_or_time.midnight.to_time
         else
           now = date_or_time.to_time.change(usec: 0)
         end
 
-        simple_stubs.stub_object(Time, :now, now)
-        simple_stubs.stub_object(Date, :today, now.to_date)
-        simple_stubs.stub_object(DateTime, :now, now.to_datetime)
+        simple_stubs.stub_object(Time, :now) { at(now.to_i) }
+        simple_stubs.stub_object(Date, :today) { jd(now.to_date.jd) }
+        simple_stubs.stub_object(DateTime, :now) { jd(now.to_date.jd, now.hour, now.min, now.sec, Rational(now.utc_offset, 86400)) }
 
         if block_given?
           begin
@@ -113,19 +174,59 @@ module ActiveSupport
       end
 
       # Returns the current time back to its original state, by removing the stubs added by
-      # `travel` and `travel_to`.
+      # +travel+, +travel_to+, and +freeze_time+.
       #
       #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
-      #   travel_to Time.new(2004, 11, 24, 01, 04, 44)
+      #
+      #   travel_to Time.zone.local(2004, 11, 24, 1, 4, 44)
       #   Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
+      #
       #   travel_back
       #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
+      #
+      # This method also accepts a block, which brings the stubs back at the end of the block:
+      #
+      #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
+      #
+      #   travel_to Time.zone.local(2004, 11, 24, 1, 4, 44)
+      #   Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
+      #
+      #   travel_back do
+      #     Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
+      #   end
+      #
+      #   Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
       def travel_back
+        stubbed_time = Time.current if block_given? && simple_stubs.stubbed?
+
         simple_stubs.unstub_all!
+        yield if block_given?
+      ensure
+        travel_to stubbed_time if stubbed_time
       end
+      alias_method :unfreeze_time, :travel_back
 
-      private
+      # Calls +travel_to+ with +Time.now+.
+      #
+      #   Time.current # => Sun, 09 Jul 2017 15:34:49 EST -05:00
+      #   freeze_time
+      #   sleep(1)
+      #   Time.current # => Sun, 09 Jul 2017 15:34:49 EST -05:00
+      #
+      # This method also accepts a block, which will return the current time back to its original
+      # state at the end of the block:
+      #
+      #   Time.current # => Sun, 09 Jul 2017 15:34:49 EST -05:00
+      #   freeze_time do
+      #     sleep(1)
+      #     User.create.created_at # => Sun, 09 Jul 2017 15:34:49 EST -05:00
+      #   end
+      #   Time.current # => Sun, 09 Jul 2017 15:34:50 EST -05:00
+      def freeze_time(&block)
+        travel_to Time.now, &block
+      end
 
+      private
         def simple_stubs
           @simple_stubs ||= SimpleStubs.new
         end

data/lib/active_support/time.rb

@@ -1,18 +1,20 @@
+# frozen_string_literal: true
+
 module ActiveSupport
-  autoload :Duration, 'active_support/duration'
-  autoload :TimeWithZone, 'active_support/time_with_zone'
-  autoload :TimeZone, 'active_support/values/time_zone'
+  autoload :Duration, "active_support/duration"
+  autoload :TimeWithZone, "active_support/time_with_zone"
+  autoload :TimeZone, "active_support/values/time_zone"
 end
 
-require 'date'
-require 'time'
+require "date"
+require "time"
 
-require 'active_support/core_ext/time'
-require 'active_support/core_ext/date'
-require 'active_support/core_ext/date_time'
+require "active_support/core_ext/time"
+require "active_support/core_ext/date"
+require "active_support/core_ext/date_time"
 
-require 'active_support/core_ext/integer/time'
-require 'active_support/core_ext/numeric/time'
+require "active_support/core_ext/integer/time"
+require "active_support/core_ext/numeric/time"
 
-require 'active_support/core_ext/string/conversions'
-require 'active_support/core_ext/string/zones'
+require "active_support/core_ext/string/conversions"
+require "active_support/core_ext/string/zones"

data/lib/active_support/time_with_zone.rb

@@ -1,7 +1,9 @@
-require 'active_support/duration'
-require 'active_support/values/time_zone'
-require 'active_support/core_ext/object/acts_like'
-require 'active_support/core_ext/date_and_time/compatibility'
+# frozen_string_literal: true
+
+require "active_support/duration"
+require "active_support/values/time_zone"
+require "active_support/core_ext/object/acts_like"
+require "active_support/core_ext/date_and_time/compatibility"
 
 module ActiveSupport
   # A Time-like class that can represent a time in any time zone. Necessary
@@ -13,37 +15,36 @@ module ActiveSupport
   # and +in_time_zone+ on Time and DateTime instances.
   #
   #   Time.zone = 'Eastern Time (US & Canada)'        # => 'Eastern Time (US & Canada)'
-  #   Time.zone.local(2007, 2, 10, 15, 30, 45)        # => Sat, 10 Feb 2007 15:30:45 EST -05:00
-  #   Time.zone.parse('2007-02-10 15:30:45')          # => Sat, 10 Feb 2007 15:30:45 EST -05:00
-  #   Time.zone.at(1171139445)                        # => Sat, 10 Feb 2007 15:30:45 EST -05:00
-  #   Time.zone.now                                   # => Sun, 18 May 2008 13:07:55 EDT -04:00
-  #   Time.utc(2007, 2, 10, 20, 30, 45).in_time_zone  # => Sat, 10 Feb 2007 15:30:45 EST -05:00
+  #   Time.zone.local(2007, 2, 10, 15, 30, 45)        # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
+  #   Time.zone.parse('2007-02-10 15:30:45')          # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
+  #   Time.zone.at(1171139445)                        # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
+  #   Time.zone.now                                   # => Sun, 18 May 2008 13:07:55.754107581 EDT -04:00
+  #   Time.utc(2007, 2, 10, 20, 30, 45).in_time_zone  # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
   #
   # See Time and TimeZone for further documentation of these methods.
   #
   # TimeWithZone instances implement the same API as Ruby Time instances, so
   # that Time and TimeWithZone instances are interchangeable.
   #
-  #   t = Time.zone.now                     # => Sun, 18 May 2008 13:27:25 EDT -04:00
+  #   t = Time.zone.now                     # => Sun, 18 May 2008 13:27:25.031505668 EDT -04:00
   #   t.hour                                # => 13
   #   t.dst?                                # => true
   #   t.utc_offset                          # => -14400
   #   t.zone                                # => "EDT"
   #   t.to_s(:rfc822)                       # => "Sun, 18 May 2008 13:27:25 -0400"
-  #   t + 1.day                             # => Mon, 19 May 2008 13:27:25 EDT -04:00
-  #   t.beginning_of_year                   # => Tue, 01 Jan 2008 00:00:00 EST -05:00
+  #   t + 1.day                             # => Mon, 19 May 2008 13:27:25.031505668 EDT -04:00
+  #   t.beginning_of_year                   # => Tue, 01 Jan 2008 00:00:00.000000000 EST -05:00
   #   t > Time.utc(1999)                    # => true
   #   t.is_a?(Time)                         # => true
   #   t.is_a?(ActiveSupport::TimeWithZone)  # => true
   class TimeWithZone
-
     # Report class name as 'Time' to thwart type checking.
     def self.name
-      'Time'
+      "Time"
     end
 
-    PRECISIONS = Hash.new { |h, n| h[n] = "%FT%T.%#{n}N".freeze }
-    PRECISIONS[0] = '%FT%T'.freeze
+    PRECISIONS = Hash.new { |h, n| h[n] = "%FT%T.%#{n}N" }
+    PRECISIONS[0] = "%FT%T"
 
     include Comparable, DateAndTime::Compatibility
     attr_reader :time_zone
@@ -56,12 +57,12 @@ module ActiveSupport
 
     # Returns a <tt>Time</tt> instance that represents the time in +time_zone+.
     def time
-      @time ||= period.to_local(@utc)
+      @time ||= incorporate_utc_offset(@utc, utc_offset)
     end
 
     # Returns a <tt>Time</tt> instance of the simultaneous time in the UTC timezone.
     def utc
-      @utc ||= period.to_utc(@time)
+      @utc ||= incorporate_utc_offset(@time, -utc_offset)
     end
     alias_method :comparable_time, :utc
     alias_method :getgm, :utc
@@ -103,13 +104,13 @@ module ActiveSupport
     #   Time.zone = 'Eastern Time (US & Canada)'    # => 'Eastern Time (US & Canada)'
     #   Time.zone.now.utc?                          # => false
     def utc?
-      period.offset.abbreviation == :UTC || period.offset.abbreviation == :UCT
+      zone == "UTC" || zone == "UCT"
     end
     alias_method :gmt?, :utc?
 
     # Returns the offset from current time to UTC time in seconds.
     def utc_offset
-      period.utc_total_offset
+      period.observed_utc_offset
     end
     alias_method :gmt_offset, :utc_offset
     alias_method :gmtoff, :utc_offset
@@ -131,14 +132,14 @@ module ActiveSupport
     #   Time.zone = 'Eastern Time (US & Canada)'   # => "Eastern Time (US & Canada)"
     #   Time.zone.now.zone # => "EST"
     def zone
-      period.zone_identifier.to_s
+      period.abbreviation
     end
 
-    # Returns a string of the object's date, time, zone and offset from UTC.
+    # Returns a string of the object's date, time, zone, and offset from UTC.
     #
-    #   Time.zone.now.inspect # => "Thu, 04 Dec 2014 11:00:25 EST -05:00"
+    #   Time.zone.now.inspect # => "Thu, 04 Dec 2014 11:00:25.624541392 EST -05:00"
     def inspect
-      "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
+      "#{time.strftime('%a, %d %b %Y %H:%M:%S.%9N')} #{zone} #{formatted_offset}"
     end
 
     # Returns a string of the object's date and time in the ISO 8601 standard
@@ -146,9 +147,10 @@ module ActiveSupport
     #
     #   Time.zone.now.xmlschema  # => "2014-12-04T11:02:37-05:00"
     def xmlschema(fraction_digits = 0)
-      "#{time.strftime(PRECISIONS[fraction_digits.to_i])}#{formatted_offset(true, 'Z'.freeze)}"
+      "#{time.strftime(PRECISIONS[fraction_digits.to_i])}#{formatted_offset(true, 'Z')}"
     end
     alias_method :iso8601, :xmlschema
+    alias_method :rfc3339, :xmlschema
 
     # Coerces time to a string for JSON encoding. The default format is ISO 8601.
     # You can get %Y/%m/%d %H:%M:%S +offset style by setting
@@ -171,12 +173,12 @@ module ActiveSupport
     end
 
     def init_with(coder) #:nodoc:
-      initialize(coder['utc'], coder['zone'], coder['time'])
+      initialize(coder["utc"], coder["zone"], coder["time"])
     end
 
     def encode_with(coder) #:nodoc:
-      coder.tag = '!ruby/object:ActiveSupport::TimeWithZone'
-      coder.map = { 'utc' => utc, 'zone' => time_zone, 'time' => time }
+      coder.tag = "!ruby/object:ActiveSupport::TimeWithZone"
+      coder.map = { "utc" => utc, "zone" => time_zone, "time" => time }
     end
 
     # Returns a string of the object's date and time in the format used by
@@ -223,6 +225,8 @@ module ActiveSupport
     def <=>(other)
       utc <=> other
     end
+    alias_method :before?, :<
+    alias_method :after?, :>
 
     # Returns true if the current object's time is within the specified
     # +min+ and +max+ time.
@@ -241,6 +245,20 @@ module ActiveSupport
       time.today?
     end
 
+    # Returns true if the current object's time falls within
+    # the next day (tomorrow).
+    def tomorrow?
+      time.tomorrow?
+    end
+    alias :next_day? :tomorrow?
+
+    # Returns true if the current object's time falls within
+    # the previous day (yesterday).
+    def yesterday?
+      time.yesterday?
+    end
+    alias :prev_day? :yesterday?
+
     # Returns true if the current object's time is in the future.
     def future?
       utc.future?
@@ -259,8 +277,8 @@ module ActiveSupport
     # value as a new TimeWithZone object.
     #
     #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
-    #   now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
-    #   now + 1000          # => Sun, 02 Nov 2014 01:43:08 EDT -04:00
+    #   now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28.725182881 EDT -04:00
+    #   now + 1000          # => Sun, 02 Nov 2014 01:43:08.725182881 EDT -04:00
     #
     # If we're adding a Duration of variable length (i.e., years, months, days),
     # move forward from #time, otherwise move forward from #utc, for accuracy
@@ -269,8 +287,8 @@ module ActiveSupport
     # For instance, a time + 24.hours will advance exactly 24 hours, while a
     # time + 1.day will advance 23-25 hours, depending on the day.
     #
-    #   now + 24.hours      # => Mon, 03 Nov 2014 00:26:28 EST -05:00
-    #   now + 1.day         # => Mon, 03 Nov 2014 01:26:28 EST -05:00
+    #   now + 24.hours      # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
+    #   now + 1.day         # => Mon, 03 Nov 2014 01:26:28.725182881 EST -05:00
     def +(other)
       if duration_of_variable_length?(other)
         method_missing(:+, other)
@@ -280,13 +298,16 @@ module ActiveSupport
       end
     end
     alias_method :since, :+
+    alias_method :in, :+
 
-    # Returns a new TimeWithZone object that represents the difference between
-    # the current object's time and the +other+ time.
+    # Subtracts an interval of time and returns a new TimeWithZone object unless
+    # the other value `acts_like?` time. Then it will return a Float of the difference
+    # between the two times that represents the difference between the current
+    # object's time and the +other+ time.
     #
     #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
-    #   now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28 EST -05:00
-    #   now - 1000          # => Mon, 03 Nov 2014 00:09:48 EST -05:00
+    #   now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
+    #   now - 1000          # => Mon, 03 Nov 2014 00:09:48.725182881 EST -05:00
     #
     # If subtracting a Duration of variable length (i.e., years, months, days),
     # move backward from #time, otherwise move backward from #utc, for accuracy
@@ -295,8 +316,14 @@ module ActiveSupport
     # For instance, a time - 24.hours will go subtract exactly 24 hours, while a
     # time - 1.day will subtract 23-25 hours, depending on the day.
     #
-    #   now - 24.hours      # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
-    #   now - 1.day         # => Sun, 02 Nov 2014 00:26:28 EDT -04:00
+    #   now - 24.hours      # => Sun, 02 Nov 2014 01:26:28.725182881 EDT -04:00
+    #   now - 1.day         # => Sun, 02 Nov 2014 00:26:28.725182881 EDT -04:00
+    #
+    # If both the TimeWithZone object and the other value act like Time, a Float
+    # will be returned.
+    #
+    #   Time.zone.now - 1.day.ago # => 86399.999967
+    #
     def -(other)
       if other.acts_like?(:time)
         to_time - other.to_time
@@ -312,8 +339,8 @@ module ActiveSupport
     # the result as a new TimeWithZone object.
     #
     #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
-    #   now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28 EST -05:00
-    #   now.ago(1000)       # => Mon, 03 Nov 2014 00:09:48 EST -05:00
+    #   now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
+    #   now.ago(1000)       # => Mon, 03 Nov 2014 00:09:48.725182881 EST -05:00
     #
     # If we're subtracting a Duration of variable length (i.e., years, months,
     # days), move backward from #time, otherwise move backward from #utc, for
@@ -323,12 +350,48 @@ module ActiveSupport
     # while <tt>time.ago(1.day)</tt> will move back 23-25 hours, depending on
     # the day.
     #
-    #   now.ago(24.hours)   # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
-    #   now.ago(1.day)      # => Sun, 02 Nov 2014 00:26:28 EDT -04:00
+    #   now.ago(24.hours)   # => Sun, 02 Nov 2014 01:26:28.725182881 EDT -04:00
+    #   now.ago(1.day)      # => Sun, 02 Nov 2014 00:26:28.725182881 EDT -04:00
     def ago(other)
       since(-other)
     end
 
+    # Returns a new +ActiveSupport::TimeWithZone+ where one or more of the elements have
+    # been changed according to the +options+ parameter. The time options (<tt>:hour</tt>,
+    # <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>, <tt>:nsec</tt>) reset cascadingly,
+    # so if only the hour is passed, then minute, sec, usec and nsec is set to 0. If the
+    # hour and minute is passed, then sec, usec and nsec is set to 0. The +options+
+    # parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>,
+    # <tt>:day</tt>, <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>,
+    # <tt>:nsec</tt>, <tt>:offset</tt>, <tt>:zone</tt>. Pass either <tt>:usec</tt>
+    # or <tt>:nsec</tt>, not both. Similarly, pass either <tt>:zone</tt> or
+    # <tt>:offset</tt>, not both.
+    #
+    #   t = Time.zone.now          # => Fri, 14 Apr 2017 11:45:15.116992711 EST -05:00
+    #   t.change(year: 2020)       # => Tue, 14 Apr 2020 11:45:15.116992711 EST -05:00
+    #   t.change(hour: 12)         # => Fri, 14 Apr 2017 12:00:00.116992711 EST -05:00
+    #   t.change(min: 30)          # => Fri, 14 Apr 2017 11:30:00.116992711 EST -05:00
+    #   t.change(offset: "-10:00") # => Fri, 14 Apr 2017 11:45:15.116992711 HST -10:00
+    #   t.change(zone: "Hawaii")   # => Fri, 14 Apr 2017 11:45:15.116992711 HST -10:00
+    def change(options)
+      if options[:zone] && options[:offset]
+        raise ArgumentError, "Can't change both :offset and :zone at the same time: #{options.inspect}"
+      end
+
+      new_time = time.change(options)
+
+      if options[:zone]
+        new_zone = ::Time.find_zone(options[:zone])
+      elsif options[:offset]
+        new_zone = ::Time.find_zone(new_time.utc_offset)
+      end
+
+      new_zone ||= time_zone
+      periods = new_zone.periods_for_local(new_time)
+
+      self.class.new(nil, new_zone, new_time, periods.include?(period) ? period : nil)
+    end
+
     # Uses Date to provide precise Time calculations for years, months, and days
     # according to the proleptic Gregorian calendar. The result is returned as a
     # new TimeWithZone object.
@@ -342,14 +405,14 @@ module ActiveSupport
     # accuracy when moving across DST boundaries.
     #
     #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
-    #   now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
-    #   now.advance(seconds: 1) # => Sun, 02 Nov 2014 01:26:29 EDT -04:00
-    #   now.advance(minutes: 1) # => Sun, 02 Nov 2014 01:27:28 EDT -04:00
-    #   now.advance(hours: 1)   # => Sun, 02 Nov 2014 01:26:28 EST -05:00
-    #   now.advance(days: 1)    # => Mon, 03 Nov 2014 01:26:28 EST -05:00
-    #   now.advance(weeks: 1)   # => Sun, 09 Nov 2014 01:26:28 EST -05:00
-    #   now.advance(months: 1)  # => Tue, 02 Dec 2014 01:26:28 EST -05:00
-    #   now.advance(years: 1)   # => Mon, 02 Nov 2015 01:26:28 EST -05:00
+    #   now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28.558049687 EDT -04:00
+    #   now.advance(seconds: 1) # => Sun, 02 Nov 2014 01:26:29.558049687 EDT -04:00
+    #   now.advance(minutes: 1) # => Sun, 02 Nov 2014 01:27:28.558049687 EDT -04:00
+    #   now.advance(hours: 1)   # => Sun, 02 Nov 2014 01:26:28.558049687 EST -05:00
+    #   now.advance(days: 1)    # => Mon, 03 Nov 2014 01:26:28.558049687 EST -05:00
+    #   now.advance(weeks: 1)   # => Sun, 09 Nov 2014 01:26:28.558049687 EST -05:00
+    #   now.advance(months: 1)  # => Tue, 02 Dec 2014 01:26:28.558049687 EST -05:00
+    #   now.advance(years: 1)   # => Mon, 02 Nov 2015 01:26:28.558049687 EST -05:00
     def advance(options)
       # If we're advancing a value of variable length (i.e., years, weeks, months, days), advance from #time,
       # otherwise advance from #utc, for accuracy when moving across DST boundaries
@@ -371,7 +434,7 @@ module ActiveSupport
     # Returns Array of parts of Time in sequence of
     # [seconds, minutes, hours, day, month, year, weekday, yearday, dst?, zone].
     #
-    #   now = Time.zone.now     # => Tue, 18 Aug 2015 02:29:27 UTC +00:00
+    #   now = Time.zone.now     # => Tue, 18 Aug 2015 02:29:27.485278555 UTC +00:00
     #   now.to_a                # => [27, 29, 2, 18, 8, 2015, 2, 230, false, "UTC"]
     def to_a
       [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
@@ -407,7 +470,18 @@ module ActiveSupport
     #   Time.zone.now.to_datetime                         # => Tue, 18 Aug 2015 02:32:20 +0000
     #   Time.current.in_time_zone('Hawaii').to_datetime   # => Mon, 17 Aug 2015 16:32:20 -1000
     def to_datetime
-      utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
+      @to_datetime ||= utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
+    end
+
+    # Returns an instance of +Time+, either with the same UTC offset
+    # as +self+ or in the local system timezone depending on the setting
+    # of +ActiveSupport.to_time_preserves_timezone+.
+    def to_time
+      if preserve_timezone
+        @to_time_with_instance_offset ||= getlocal(utc_offset)
+      else
+        @to_time_with_system_offset ||= getlocal
+      end
     end
 
     # So that +self+ <tt>acts_like?(:time)</tt>.
@@ -427,7 +501,8 @@ module ActiveSupport
     end
 
     def freeze
-      period; utc; time # preload instance variables before freezing
+      # preload instance variables before freezing
+      period; utc; time; to_datetime; to_time
       super
     end
 
@@ -459,10 +534,20 @@ module ActiveSupport
     def method_missing(sym, *args, &block)
       wrap_with_time_zone time.__send__(sym, *args, &block)
     rescue NoMethodError => e
-      raise e, e.message.sub(time.inspect, self.inspect), e.backtrace
+      raise e, e.message.sub(time.inspect, inspect), e.backtrace
     end
 
     private
+      SECONDS_PER_DAY = 86400
+
+      def incorporate_utc_offset(time, offset)
+        if time.kind_of?(Date)
+          time + Rational(offset, SECONDS_PER_DAY)
+        else
+          time + offset
+        end
+      end
+
       def get_period_and_ensure_valid_local_time(period)
         # we don't want a Time.local instance enforcing its own DST rules as well,
         # so transfer time values to a utc constructor if necessary
@@ -477,11 +562,13 @@ module ActiveSupport
       end
 
       def transfer_time_values_to_utc_constructor(time)
+        # avoid creating another Time object if possible
+        return time if time.instance_of?(::Time) && time.utc?
         ::Time.utc(time.year, time.month, time.day, time.hour, time.min, time.sec + time.subsec)
       end
 
       def duration_of_variable_length?(obj)
-        ActiveSupport::Duration === obj && obj.parts.any? {|p| [:years, :months, :days].include?(p[0]) }
+        ActiveSupport::Duration === obj && obj.parts.any? { |p| [:years, :months, :weeks, :days].include?(p[0]) }
       end
 
       def wrap_with_time_zone(time)