Equality comparisons between dates and times can take some extra time to
comprehend. I tend to think of a date or time as "before" or "after"
another date or time, but I naturally read `<` and `>` as "less than"
and "greater than." This change seeks to make date/time comparisons more
human readable.

Follow up of #31432.

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

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

Fixes #28723.

For naming consistency when using the RFC 3339 profile
of ISO 8601 in applications.

The `Time.xmlschema` and consequently its alias `iso8601` accepts
timestamps without a offset in contravention of the RFC 3339
standard. This method enforces that constraint and raises an
`ArgumentError` if it doesn't.

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

Time instances can have fractional parts smaller than a nanosecond.

The default timestamp used for AR is `updated_at` in nanoseconds! (:nsec) This causes issues on any machine that runs an OS that supports nanoseconds timestamps, i.e. not-OS X, where the cache_key of the record persisted in the database (milliseconds precision) is out-of-sync with the cache_key in the ruby VM.

This commit adds:

A test that shows the issue, it can be found in the separate file `cache_key_test.rb`, because
- model couldn't be defined inline
- transactional testing needed to be turned off to get it to pass the MySQL tests
This seemed cleaner than putting it in an existing testcase file.

It adds :usec as a dateformat that calculates datetime in microseconds

It sets precision of cache_key to :usec instead of :nsec, as no db supports nsec precision on timestamps

Passing 999999000 < `:nsec` < 999999999 and 999999 < `:usec` < 1000000
to change a time with utc_offset doesn't throw an `ArgumentError`.

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.

Closes #16392.

https://github.com/rails/rails/commit/98b46bf5e201307cae56ee14bf41363a539779c5
did not properly handled out-of-range `:usec`s.

Passing a `:usec` that's out of range now throws an `ArgumentError` as it
should.

Fixes #16759.

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

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.

Add Time#to_s(:iso8601) for easy conversion of times to the iso8601 format for easy Javascript date parsing

Added middle_of_day method to Date and DateTime

The standard Ruby behavior for Time.at is to return the same type of
time when passing an instance of Time as a single argument. Since the
an ActiveSupport::TimeWithZone instance may be a different timezone than
the system timezone and DateTime just understands offsets the best we
can do is to return an instance of Time with the correct offset.

Fixes #11350.

When Time.at_with_coercion (wraps Time.at) is called with a single
argument that "acts_like?(:time)" it is coerced to integer thus losing
it's microsecond percision.

This commits changes this to use `#to_f` to prevent the problem

    and `Time#local_time` in favour of `Time#utc` and `Time#local`

Time.at allows passing a single Time argument which is then converted
to an integer. The conversion code since 1.9.3r429 explicitly checks
for an instance of Time so we need to override it to allow DateTime
and ActiveSupport::TimeWithZone values.

Time#advance uses Time#to_date and Date#advance to calculate a new date.
The Date object returned by Time#to_date is constructed with the assumption
that the Time object represents a proleptic gregorian date, but it is
configured to observe the default julian calendar reform date (2299161j)
for purposes of calculating month, date and year:

  Time.new(1582, 10, 4).to_date.to_s           # => "1582-09-24"
  Time.new(1582, 10, 4).to_date.gregorian.to_s # => "1582-10-04"

This patch ensures that when the intermediate Date object is advanced
to yield a new Date object, that the Time object for return is contructed
with a proleptic gregorian month, date and year.

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