Add additional options to time `change` methods

Support `:offset` in `Time#change` and `:zone` or `:offset`
in `ActiveSupport::TimeWithZone#change`.

Fixes #28723.

2 files changed, 57 insertions, 15 deletions

diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb
index 7b7aeef25a..d3f23f4663 100644
--- a/activesupport/lib/active_support/core_ext/time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/time/calculations.rb
@@ -107,21 +107,22 @@ class Time
   # 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>. Pass either <tt>:usec</tt> or <tt>:nsec</tt>, not both.
+  # 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>. Pass either <tt>:usec</tt> or <tt>:nsec</tt>, not both.
   #
   #   Time.new(2012, 8, 29, 22, 35, 0).change(day: 1)              # => Time.new(2012, 8, 1, 22, 35, 0)
   #   Time.new(2012, 8, 29, 22, 35, 0).change(year: 1981, day: 1)  # => Time.new(1981, 8, 1, 22, 35, 0)
   #   Time.new(2012, 8, 29, 22, 35, 0).change(year: 1981, hour: 0) # => Time.new(1981, 8, 29, 0, 0, 0)
   def change(options)
-    new_year  = options.fetch(:year, year)
-    new_month = options.fetch(:month, month)
-    new_day   = options.fetch(:day, day)
-    new_hour  = options.fetch(:hour, hour)
-    new_min   = options.fetch(:min, options[:hour] ? 0 : min)
-    new_sec   = options.fetch(:sec, (options[:hour] || options[:min]) ? 0 : sec)
+    new_year   = options.fetch(:year, year)
+    new_month  = options.fetch(:month, month)
+    new_day    = options.fetch(:day, day)
+    new_hour   = options.fetch(:hour, hour)
+    new_min    = options.fetch(:min, options[:hour] ? 0 : min)
+    new_sec    = options.fetch(:sec, (options[:hour] || options[:min]) ? 0 : sec)
+    new_offset = options.fetch(:offset, nil)
 
     if new_nsec = options[:nsec]
       raise ArgumentError, "Can't change both :nsec and :usec at the same time: #{options.inspect}" if options[:usec]
@@ -130,13 +131,18 @@ class Time
       new_usec = options.fetch(:usec, (options[:hour] || options[:min] || options[:sec]) ? 0 : Rational(nsec, 1000))
     end
 
-    if utc?
-      ::Time.utc(new_year, new_month, new_day, new_hour, new_min, new_sec, new_usec)
+    raise ArgumentError, "argument out of range" if new_usec >= 1000000
+
+    new_sec += Rational(new_usec, 1000000)
+
+    if new_offset
+      ::Time.new(new_year, new_month, new_day, new_hour, new_min, new_sec, new_offset)
+    elsif utc?
+      ::Time.utc(new_year, new_month, new_day, new_hour, new_min, new_sec)
     elsif zone
-      ::Time.local(new_year, new_month, new_day, new_hour, new_min, new_sec, new_usec)
+      ::Time.local(new_year, new_month, new_day, new_hour, new_min, new_sec)
     else
-      raise ArgumentError, "argument out of range" if new_usec >= 1000000
-      ::Time.new(new_year, new_month, new_day, new_hour, new_min, new_sec + (new_usec.to_r / 1000000), utc_offset)
+      ::Time.new(new_year, new_month, new_day, new_hour, new_min, new_sec, utc_offset)
     end
   end
 
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index b0dd6b7e8c..ecb9fb6785 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -330,6 +330,42 @@ module ActiveSupport
       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 EST -05:00
+    #   t.change(year: 2020)       # => Tue, 14 Apr 2020 11:45:15 EST -05:00
+    #   t.change(hour: 12)         # => Fri, 14 Apr 2017 12:00:00 EST -05:00
+    #   t.change(min: 30)          # => Fri, 14 Apr 2017 11:30:00 EST -05:00
+    #   t.change(offset: "-10:00") # => Fri, 14 Apr 2017 11:45:15 HST -10:00
+    #   t.change(zone: "Hawaii")   # => Fri, 14 Apr 2017 11:45:15 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.