Deprecate obsolete Time to DateTime fallback methods

The Time.time_with_datetime_fallback, Time.utc_time and Time.local_time
methods were added to handle the limitations of Ruby's native Time
implementation. Those limitations no longer apply so we are deprecating
them in 4.0 and they will be removed in 4.1.

10 files changed, 62 insertions, 33 deletions

diff --git a/activesupport/CHANGELOG.md b/activesupport/CHANGELOG.md
index 73d4837e46..7b93731917 100644
--- a/activesupport/CHANGELOG.md
+++ b/activesupport/CHANGELOG.md
@@ -1,5 +1,12 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   Deprecate `Time.time_with_date_fallback`, `Time.utc_time` and `Time.local_time`.
+    These methods were added to handle the limited range of Ruby's native Time
+    implementation. Those limitations no longer apply so we are deprecating them in 4.0
+    and they will be removed in 4.1.
+
+    *Andrew White*
+
 *   Deprecate `Date#to_time_in_current_zone` and add `Date#in_time_zone`. *Andrew White*
 
 *   Add `String#in_time_zone` method to convert a string to an ActiveSupport::TimeWithZone. *Andrew White*
diff --git a/activesupport/lib/active_support/core_ext/date/conversions.rb b/activesupport/lib/active_support/core_ext/date/conversions.rb
index d49d427d80..fe08ade7e0 100644
--- a/activesupport/lib/active_support/core_ext/date/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date/conversions.rb
@@ -75,7 +75,7 @@ class Date
   #
   #   date.to_time(:utc)             # => Sat Nov 10 00:00:00 UTC 2007
   def to_time(form = :local)
-    ::Time.send("#{form}_time", year, month, day)
+    ::Time.send(form, year, month, day)
   end
 
   def xmlschema
diff --git a/activesupport/lib/active_support/core_ext/string/conversions.rb b/activesupport/lib/active_support/core_ext/string/conversions.rb
index 9b9d83932e..9d3b81cf38 100644
--- a/activesupport/lib/active_support/core_ext/string/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/string/conversions.rb
@@ -21,7 +21,7 @@ class String
       date_values[6] *= 1000000
       offset = date_values.pop
 
-      ::Time.send("#{form}_time", *date_values) - offset
+      ::Time.send(form, *date_values) - offset
     end
   end
 
diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb
index 1f17378c8d..1f95f62229 100644
--- a/activesupport/lib/active_support/core_ext/time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/time/calculations.rb
@@ -3,6 +3,7 @@ require 'active_support/core_ext/time/conversions'
 require 'active_support/time_with_zone'
 require 'active_support/core_ext/time/zones'
 require 'active_support/core_ext/date_and_time/calculations'
+require 'active_support/deprecation'
 
 class Time
   include DateAndTime::Calculations
@@ -25,10 +26,13 @@ class Time
       end
     end
 
+    # *DEPRECATED*: Use +Time#utc+ or +Time#local+ instead.
+    #
     # Returns a new Time if requested year can be accommodated by Ruby's Time class
     # (i.e., if year is within either 1970..2038 or 1902..2038, depending on system architecture);
     # otherwise returns a DateTime.
     def time_with_datetime_fallback(utc_or_local, year, month=1, day=1, hour=0, min=0, sec=0, usec=0)
+      ActiveSupport::Deprecation.warn 'time_with_datetime_fallback is deprecated. Use Time#utc or Time#local instead', caller
       time = ::Time.send(utc_or_local, year, month, day, hour, min, sec, usec)
 
       # This check is needed because Time.utc(y) returns a time object in the 2000s for 0 <= y <= 138.
@@ -41,13 +45,19 @@ class Time
       ::DateTime.civil_from_format(utc_or_local, year, month, day, hour, min, sec)
     end
 
+    # *DEPRECATED*: Use +Time#utc+ instead.
+    #
     # Wraps class method +time_with_datetime_fallback+ with +utc_or_local+ set to <tt>:utc</tt>.
     def utc_time(*args)
+      ActiveSupport::Deprecation.warn 'utc_time is deprecated. Use Time#utc instead', caller
       time_with_datetime_fallback(:utc, *args)
     end
 
+    # *DEPRECATED*: Use +Time#local+ instead.
+    #
     # Wraps class method +time_with_datetime_fallback+ with +utc_or_local+ set to <tt>:local</tt>.
     def local_time(*args)
+      ActiveSupport::Deprecation.warn 'local_time is deprecated. Use Time#local instead', caller
       time_with_datetime_fallback(:local, *args)
     end
 
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index b931de3fac..0dbc198ea2 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -344,7 +344,7 @@ module ActiveSupport
       end
 
       def transfer_time_values_to_utc_constructor(time)
-        ::Time.utc_time(time.year, time.month, time.day, time.hour, time.min, time.sec, time.respond_to?(:nsec) ? Rational(time.nsec, 1000) : 0)
+        ::Time.utc(time.year, time.month, time.day, time.hour, time.min, time.sec, Rational(time.nsec, 1000))
       end
 
       def duration_of_variable_length?(obj)
diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb
index d087955587..c5fbddcb5f 100644
--- a/activesupport/lib/active_support/values/time_zone.rb
+++ b/activesupport/lib/active_support/values/time_zone.rb
@@ -252,7 +252,7 @@ module ActiveSupport
     #   Time.zone = 'Hawaii'                    # => "Hawaii"
     #   Time.zone.local(2007, 2, 1, 15, 30, 45) # => Thu, 01 Feb 2007 15:30:45 HST -10:00
     def local(*args)
-      time = Time.utc_time(*args)
+      time = Time.utc(*args)
       ActiveSupport::TimeWithZone.new(nil, self, time)
     end
 
diff --git a/activesupport/test/core_ext/date_ext_test.rb b/activesupport/test/core_ext/date_ext_test.rb
index 278ee96796..5e89a6e00b 100644
--- a/activesupport/test/core_ext/date_ext_test.rb
+++ b/activesupport/test/core_ext/date_ext_test.rb
@@ -34,7 +34,7 @@ class DateExtCalculationsTest < ActiveSupport::TestCase
 
   def test_to_time
     assert_equal Time.local(2005, 2, 21), Date.new(2005, 2, 21).to_time
-    assert_equal Time.local_time(2039, 2, 21), Date.new(2039, 2, 21).to_time
+    assert_equal Time.local(2039, 2, 21), Date.new(2039, 2, 21).to_time
     silence_warnings do
       0.upto(138) do |year|
         [:utc, :local].each do |format|
diff --git a/activesupport/test/core_ext/date_time_ext_test.rb b/activesupport/test/core_ext/date_time_ext_test.rb
index 3353465c1c..dfad3a90f8 100644
--- a/activesupport/test/core_ext/date_time_ext_test.rb
+++ b/activesupport/test/core_ext/date_time_ext_test.rb
@@ -42,7 +42,7 @@ class DateTimeExtCalculationsTest < ActiveSupport::TestCase
 
   def test_to_time
     assert_equal Time.utc(2005, 2, 21, 10, 11, 12), DateTime.new(2005, 2, 21, 10, 11, 12, 0).to_time
-    assert_equal Time.utc_time(2039, 2, 21, 10, 11, 12), DateTime.new(2039, 2, 21, 10, 11, 12, 0).to_time
+    assert_equal Time.utc(2039, 2, 21, 10, 11, 12), DateTime.new(2039, 2, 21, 10, 11, 12, 0).to_time
     # DateTimes with offsets other than 0 are returned unaltered
     assert_equal DateTime.new(2005, 2, 21, 10, 11, 12, Rational(-5, 24)), DateTime.new(2005, 2, 21, 10, 11, 12, Rational(-5, 24)).to_time
     # Fractional seconds are preserved
diff --git a/activesupport/test/core_ext/string_ext_test.rb b/activesupport/test/core_ext/string_ext_test.rb
index 7ebacc8720..fa8839bcb3 100644
--- a/activesupport/test/core_ext/string_ext_test.rb
+++ b/activesupport/test/core_ext/string_ext_test.rb
@@ -291,7 +291,7 @@ class StringConversionsTest < ActiveSupport::TestCase
     assert_equal Time.utc(2005, 2, 27, 23, 50, 19, 275038), "2005-02-27T23:50:19.275038".to_time
     assert_equal Time.local(2005, 2, 27, 23, 50, 19, 275038), "2005-02-27T23:50:19.275038".to_time(:local)
     assert_equal DateTime.civil(2039, 2, 27, 23, 50), "2039-02-27 23:50".to_time
-    assert_equal Time.local_time(2039, 2, 27, 23, 50), "2039-02-27 23:50".to_time(:local)
+    assert_equal Time.local(2039, 2, 27, 23, 50), "2039-02-27 23:50".to_time(:local)
     assert_equal Time.utc(2011, 2, 27, 23, 50), "2011-02-27 22:50 -0100".to_time
     assert_nil "".to_time
   end
diff --git a/activesupport/test/core_ext/time_ext_test.rb b/activesupport/test/core_ext/time_ext_test.rb
index 0e75104fc6..70e07cefd1 100644
--- a/activesupport/test/core_ext/time_ext_test.rb
+++ b/activesupport/test/core_ext/time_ext_test.rb
@@ -567,45 +567,57 @@ class TimeExtCalculationsTest < ActiveSupport::TestCase
   end
 
   def test_time_with_datetime_fallback
-    assert_equal Time.time_with_datetime_fallback(:utc, 2005, 2, 21, 17, 44, 30), Time.utc(2005, 2, 21, 17, 44, 30)
-    assert_equal Time.time_with_datetime_fallback(:local, 2005, 2, 21, 17, 44, 30), Time.local(2005, 2, 21, 17, 44, 30)
-    assert_equal Time.time_with_datetime_fallback(:utc, 2039, 2, 21, 17, 44, 30), DateTime.civil(2039, 2, 21, 17, 44, 30, 0)
-    assert_equal Time.time_with_datetime_fallback(:local, 2039, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 2039, 2, 21, 17, 44, 30)
-    assert_equal Time.time_with_datetime_fallback(:utc, 1900, 2, 21, 17, 44, 30), DateTime.civil(1900, 2, 21, 17, 44, 30, 0)
-    assert_equal Time.time_with_datetime_fallback(:utc, 2005), Time.utc(2005)
-    assert_equal Time.time_with_datetime_fallback(:utc, 2039), DateTime.civil(2039, 1, 1, 0, 0, 0, 0)
-    assert_equal Time.time_with_datetime_fallback(:utc, 2005, 2, 21, 17, 44, 30, 1), Time.utc(2005, 2, 21, 17, 44, 30, 1) #with usec
-    # This won't overflow on 64bit linux
-    unless time_is_64bits?
-      assert_equal Time.time_with_datetime_fallback(:local, 1900, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 1900, 2, 21, 17, 44, 30)
-      assert_equal Time.time_with_datetime_fallback(:utc, 2039, 2, 21, 17, 44, 30, 1),
-                   DateTime.civil(2039, 2, 21, 17, 44, 30, 0, 0)
-      assert_equal ::Date::ITALY, Time.time_with_datetime_fallback(:utc, 2039, 2, 21, 17, 44, 30, 1).start # use Ruby's default start value
-    end
-    silence_warnings do
-      0.upto(138) do |year|
-        [:utc, :local].each do |format|
-          assert_equal year, Time.time_with_datetime_fallback(format, year).year
+    ActiveSupport::Deprecation.silence do
+      assert_equal Time.time_with_datetime_fallback(:utc, 2005, 2, 21, 17, 44, 30), Time.utc(2005, 2, 21, 17, 44, 30)
+      assert_equal Time.time_with_datetime_fallback(:local, 2005, 2, 21, 17, 44, 30), Time.local(2005, 2, 21, 17, 44, 30)
+      assert_equal Time.time_with_datetime_fallback(:utc, 2039, 2, 21, 17, 44, 30), DateTime.civil(2039, 2, 21, 17, 44, 30, 0)
+      assert_equal Time.time_with_datetime_fallback(:local, 2039, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 2039, 2, 21, 17, 44, 30)
+      assert_equal Time.time_with_datetime_fallback(:utc, 1900, 2, 21, 17, 44, 30), DateTime.civil(1900, 2, 21, 17, 44, 30, 0)
+      assert_equal Time.time_with_datetime_fallback(:utc, 2005), Time.utc(2005)
+      assert_equal Time.time_with_datetime_fallback(:utc, 2039), DateTime.civil(2039, 1, 1, 0, 0, 0, 0)
+      assert_equal Time.time_with_datetime_fallback(:utc, 2005, 2, 21, 17, 44, 30, 1), Time.utc(2005, 2, 21, 17, 44, 30, 1) #with usec
+      # This won't overflow on 64bit linux
+      unless time_is_64bits?
+        assert_equal Time.time_with_datetime_fallback(:local, 1900, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 1900, 2, 21, 17, 44, 30)
+        assert_equal Time.time_with_datetime_fallback(:utc, 2039, 2, 21, 17, 44, 30, 1),
+                     DateTime.civil(2039, 2, 21, 17, 44, 30, 0, 0)
+        assert_equal ::Date::ITALY, Time.time_with_datetime_fallback(:utc, 2039, 2, 21, 17, 44, 30, 1).start # use Ruby's default start value
+      end
+      silence_warnings do
+        0.upto(138) do |year|
+          [:utc, :local].each do |format|
+            assert_equal year, Time.time_with_datetime_fallback(format, year).year
+          end
         end
       end
     end
   end
 
   def test_utc_time
-    assert_equal Time.utc_time(2005, 2, 21, 17, 44, 30), Time.utc(2005, 2, 21, 17, 44, 30)
-    assert_equal Time.utc_time(2039, 2, 21, 17, 44, 30), DateTime.civil(2039, 2, 21, 17, 44, 30, 0)
-    assert_equal Time.utc_time(1901, 2, 21, 17, 44, 30), DateTime.civil(1901, 2, 21, 17, 44, 30, 0)
+    ActiveSupport::Deprecation.silence do
+      assert_equal Time.utc_time(2005, 2, 21, 17, 44, 30), Time.utc(2005, 2, 21, 17, 44, 30)
+      assert_equal Time.utc_time(2039, 2, 21, 17, 44, 30), DateTime.civil(2039, 2, 21, 17, 44, 30, 0)
+      assert_equal Time.utc_time(1901, 2, 21, 17, 44, 30), DateTime.civil(1901, 2, 21, 17, 44, 30, 0)
+    end
   end
 
   def test_local_time
-    assert_equal Time.local_time(2005, 2, 21, 17, 44, 30), Time.local(2005, 2, 21, 17, 44, 30)
-    assert_equal Time.local_time(2039, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 2039, 2, 21, 17, 44, 30)
+    ActiveSupport::Deprecation.silence do
+      assert_equal Time.local_time(2005, 2, 21, 17, 44, 30), Time.local(2005, 2, 21, 17, 44, 30)
+      assert_equal Time.local_time(2039, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 2039, 2, 21, 17, 44, 30)
 
-    unless time_is_64bits?
-      assert_equal Time.local_time(1901, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 1901, 2, 21, 17, 44, 30)
+      unless time_is_64bits?
+        assert_equal Time.local_time(1901, 2, 21, 17, 44, 30), DateTime.civil_from_format(:local, 1901, 2, 21, 17, 44, 30)
+      end
     end
   end
 
+  def test_time_with_datetime_fallback_deprecations
+    assert_deprecated(/time_with_datetime_fallback/) { Time.time_with_datetime_fallback(:utc, 2012, 6, 7) }
+    assert_deprecated(/utc_time/) { Time.utc_time(2012, 6, 7) }
+    assert_deprecated(/local_time/) { Time.local_time(2012, 6, 7) }
+  end
+
   def test_last_month_on_31st
     assert_equal Time.local(2004, 2, 29), Time.local(2004, 3, 31).last_month
   end