These methods were originally added in https://github.com/rails/rails/pull/26600

This includes a couple of refactors to make these methods behave more similarly to other Date/Time extensions added by Active Support:

1. Use `advance` instead of `since` and `ago` to time-travel — this is particularly important to keep the returned instance’s class matching `self`.  Before this change:

    today = Date.today                     # => Tue, 28 Nov 2017
    today.class                            # => Date
    today.next_occurring(:wednesday)       # => Wed, 29 Nov 2017 00:00:00 UTC +00:00
    today.next_occurring(:wednesday).class # => ActiveSupport::TimeWithZone

  After this change, a Date (or Time, or DateTime) instance is properly returned (just like is shown in the new docs).  This is generally how everything else in DateAndTime::Calculations works.

2. Move the tests from the DateTime tests to the DateAndTimeBehavior tests.  The latter location is mixed in to the core_ext tests for _all_ of Date, Time, and DateTime to test the behavior across all of the classes.  The previous location is for testing core_ext functionality added specifically just to DateTime.

3. Better docs!

This reverts commit 3420a145, reversing
changes made to afb66a5a.

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

Fixes #28723.

Adding support for these options now allows us to update the
`DateTime#end_of` methods to match the equivalent `Time#end_of`
methods, e.g:

    datetime = DateTime.now.end_of_day
    datetime.nsec == 999999999 # => true

Fixes #21424.

The current code base is not uniform. After some discussion,
we have chosen to go with double quotes by default.

These two tests are explicitly testing that to_time is returning times
with the sytem timezone's UTC offset, therefore they will fail when
running them with `ActiveSupport.to_time_preserves_timezone = true`.

Previously these methods could return either a DateTime or a Time
depending on how the ActiveSupport::TimeWithZone instance had
been constructed. Changing to always return an instance of Time
eliminates a possible stack level too deep error in to_time where
it was wrapping a DateTime instance.

As a consequence of this the internal time value is now always an
instance of Time in the UTC timezone, whether that's as the UTC
time directly or a representation of the local time in the timezone.

There should be no consequences of this internal change and if
there are it's a bug due to leaky abstractions.

Mirrors the Time#subsec method by returning the fraction
of the second as a Rational.

In Ruby 2.4 the `to_time` method for both `DateTime` and `Time` will
preserve the timezone of the receiver when converting to an instance
of `Time`. Since Rails 5.0 will support Ruby 2.2, 2.3 and later we
need to introduce a compatibility layer so that apps that upgrade do
not break. New apps will have a config initializer file that defaults
to match the new Ruby 2.4 behavior going forward.

For information about the changes to Ruby see:
https://bugs.ruby-lang.org/issues/12189
https://bugs.ruby-lang.org/issues/12271

Fixes #24617.

The native DateTime#<=> implementation can be used to compare instances
with numeric values being considered as astronomical julian day numbers
so we should call that instead of returning nil.

Fixes #24228.

Fixing failing specification for verifying the last week when the year is leap

before:

    p Time.now ==  'a'  # => false
    p Time.now <=> 'a'  # => nil

    require 'active_support'
    require 'active_support/core_ext'

    p Time.now ==  'a'  # => false
    p Time.now <=> 'a'  # => invalid date (ArgumentError)

and on ruby 2.2, Time.now == 'a' warning.

    warning: Comparable#== will no more rescue exceptions of #<=> in the next release.
    warning: Return nil in #<=> if the comparison is inappropriate or avoid such comparison.

after:

- Error handling.
- Quiet warnings.

Previously this method always returns `.0` in the fractional part. This commit
changes it to preserve the fractional seconds instead.

Fixes #15994.

It’s used at so many places that extracting it out into a helper file
is worth doing.

You can now add partial days (e.g. 2.5.days) to `DateTime` with the advance method.
This was acheived by mimicing the `advance` implementation in `Time`.

Use a lambda to ensure that the generated string respects the offset of
the time value. Also add DateTime#to_s(:iso8601) and Date#to_s(:iso8601)
for completeness.

Added middle_of_day method to Date and DateTime

Add `DateTime#usec` and `DateTime#nsec` so that `ActiveSupport::TimeWithZone`
keeps sub-second resolution when wrapping a `DateTime` value.

Fixes #10855

commit 2683de5da85135e8d9fe48593ff6167db9d64b18
Author: Aaron Patterson <aaron.patterson@gmail.com>
Date:   Fri May 3 11:29:20 2013 -0700

    cannot support infinite ranges right now

commit cebb6acef2c3957f975f6db4afd849e535126253
Author: Aaron Patterson <aaron.patterson@gmail.com>
Date:   Fri May 3 11:26:12 2013 -0700

    reverting infinity comparison

commit 385f7e6b4efd1bf9b89e8d607fcb13e5b03737ea
Author: Aaron Patterson <aaron.patterson@gmail.com>
Date:   Fri May 3 11:23:28 2013 -0700

    Revert "Added ability to compare date/time with infinity"

    This reverts commit 38f28dca.

    Conflicts:
    	activesupport/CHANGELOG.md
    	activesupport/lib/active_support/core_ext/numeric/infinite_comparable.rb
    	activesupport/test/core_ext/date_ext_test.rb
    	activesupport/test/core_ext/date_time_ext_test.rb
    	activesupport/test/core_ext/numeric_ext_test.rb
    	activesupport/test/core_ext/time_ext_test.rb
    	activesupport/test/core_ext/time_with_zone_test.rb

commit 0d799a188dc12b18267fc8421675729917610047
Author: Aaron Patterson <aaron.patterson@gmail.com>
Date:   Fri May 3 11:18:53 2013 -0700

    Revert "Refactor infinite comparable definition a bit"

    This reverts commit dd3360e0.

commit 42dec90e49745bbfae546f0560b8783f6b48b074
Author: Aaron Patterson <aaron.patterson@gmail.com>
Date:   Fri May 3 11:18:47 2013 -0700

    Revert "Require 'active_support/core_ext/module/aliasing' in the infinite_comparable module"

    This reverts commit 7003e71c.

This commit standardises the return value of `to_time` to an instance
of `Time` in the local system timezone, matching the Ruby core and
standard library behavior.

The default form for `String#to_time` has been changed from :utc to
:local but research seems to suggest the latter is the more common form.

Also fix an edge condition with `String#to_time` where the string has
a timezone offset in it and the mode is :local. e.g:

  # Before:
  >> "2000-01-01 00:00:00 -0500".to_time(:local)
  => 2000-01-01 05:00:00 -0500

  # After:
  >> "2000-01-01 00:00:00 -0500".to_time(:local)
  => 2000-01-01 00:00:00 -0500

Closes #2453

Date, DateTime, Time and TimeWithZone can now be compared to infinity,
  so it's now possible to create ranges with one infinite bound and
  date/time object as another bound.

  Ex.: @range = Range.new(Date.today, Float::INFINITY)

Also it's possible to check inclusion of date/time in range with
  conversion.

  Ex.: @range.include?(Time.now + 1.year) # => true
       @range.include?(DateTime.now + 1.year) # => true

Ability to create date/time ranges with infinite bound is required
  for handling postgresql range types.

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.

* Added the `DateAndTime::Calculations` module that is included in Time
  and Date. It houses common calculations to reduce duplicated code.
* Simplified and cleaned-up the calculation code.
* Removed duplication in tests by adding a behavior module for shared
  tests. I also added some missing tests.

Calculate the seconds since the UNIX epoch using the difference in
Julian day numbers from the epoch date. By reducing the Rational math
to just the offset component this gives a significant improvement.

Benchmark:

Calculating --------------------------------------------
       new     27733 i/100ms
   current     15031 i/100ms
       new     27737 i/100ms
   current     15549 i/100ms
--------------------------------------------------------
       new   548182.1 (±0.9%) i/s - 2745567 in 5.008943s
   current   216380.9 (±1.6%) i/s - 1082232 in 5.002781s
       new   510281.9 (±1.2%) i/s - 2551804 in 5.001525s
   current   219858.3 (±1.8%) i/s - 1103979 in 5.023039s