`find_nth` is protected method, therefore `offset` has not been passed
anywhere. `find_nth_with_limit_and_offset` is unnecessary anymore
because `offset` has not been passed.

Some case expressions remain, need to think about those ones.

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

`FinderMethods#exists?` should return a boolean rather than raising an
exception.

`UniquenessValidator#build_relation` catches a `RangeError` because it
includes type casting due to a string value truncation. But a string
value truncation was removed at #23523 then type casting in
`build_relation` is no longer necessary. aa062318 removes type casting in
`build_relation` then a `RangeError` moves to `relation.exists?`.

This change will remove the catching a `RangeError`.

`construct_relation_for_association_calculations` pass a string value to
`construct_join_dependency` when setting a string value in `from`.
It should not pass a string value, but always `joins_values`.

Related #14834, #19452.

Fixes #24193.

Currently `exists?` does some hackery where it assumes that we can join
onto anything that we passed to `eager_load` or `includes`, which
doesn't work if we are joining onto a polymorphic association.

Actually figuring out if we want to include something would require
knowledge deep within the join dependency module, which is hard to pull
up. The simplest solution is just to pass a flag down that says we're
not actually going to try to eager load any of the data. It's not the
solution I'd like, but that code really needs to be untangled before we
can do much with it.

This is another attempt at 6d5b1fdf which should address the concerns
that led to reverting it in 4ecabed2.

- we are ending sentences properly
- fixing of space issues
- fixed continuity issues in some sentences.

Reverts https://github.com/rails/rails/commit/8fc97d198ef31c1d7a4b9b849b96fc08a667fb02 .
This change reverts making sure we add '.' at end of deprecation sentences.
This is to keep sentences within Rails itself consistent and with a '.' at the end.

We should use #find_or_initialize_by and #find_or_create_by because #first_or_initialize and #first_or_create methods are not the public API

Clarifying this separation and enforcing relation immutability is the
culmination of the previous efforts to remove the mutator method
delegations.

instead of loading the relation into memory

This removes the following warnings.

```
activerecord/lib/active_record/relation/finder_methods.rb:252: warning: ambiguous first argument; put parentheses or a space even after `-' operator
activerecord/lib/active_record/relation/finder_methods.rb:258: warning: ambiguous first argument; put parentheses or a space even after `-' operator
activerecord/lib/active_record/relation/finder_methods.rb:268: warning: ambiguous first argument; put parentheses or a space even after `-' operator
activerecord/lib/active_record/relation/finder_methods.rb:274: warning: ambiguous first argument; put parentheses or a space even after `-' operator
```

This still isn't as separated as I'd like, but it at least moves most of
the burden of alias mapping in one place.

This reverts commit 9f3730a5, reversing
changes made to 2637fb75.

There are additional issues with this commit that need to be addressed
before this change is ready (see #23377). This is a temporary revert in
order for us to have more time to address the issues with that PR,
without blocking the release of beta2.

instead of loading relation

@bogdan pointed out that a `loaded?` relation would not warn that the supplied
offset would be removed. This fixes that oversight.

https://github.com/rails/rails/commit/16a476e4f8f802774ae7c8dca2e59f4e672dc591#commitcomment-15706834

Although this second argument is probably not widely used, and would be
ignored anyway in the loaded? case, this could protect callers from gotchas.

[Ben Woosley & Victor Kmita]

I realized that `first(2)`, etc. was unnecessarily querying for the
records when they were already preloaded. This was because
`find_nth_with_limit` can not know which `@records` to return because
it conflates the `offset` and `index` into a single variable, while
the `@records` only needs the `index` itself to select the proper
record.

Because `find_nth` and `find_nth_with_limit` are public methods, I
instead introduced a private method `find_nth_with_limit_and_offset`
which is called internally and handles the `loaded?` checking.

Once the `offset` argument is removed from `find_nth`,
`find_nth_with_limit_and_offset` can be collapsed into
`find_nth_with_limit`, with `offset` always equal to `offset_index`.

All uses of the `offset` are passing `offset_index`. Better to push
down the `offset` consideration into `find_nth`.

This also works toward enabling `find_nth_with_limit` to take
advantage of the `loaded?` state of the relation.

We know the query will return exactly one row for each entry in the
`ids` array, so we can do all the limit/offset calculations on that
array, in advance.

I also split our new ordered-ids behaviour out of the existing
`find_some` method: especially with this change, the conditionals were
overwhelming the actual logic.

This reverts commit 6d5b1fdf.

`eager_load` and `references` can include hashes, which won't match up
with `references`

A test case has been added to demonstrate the problem

This was changed in 421c81bd, as `exists?` blows up if you are eager
loading a polymorphic association, as it'll try to construct a join to
that table. The previous change decided to execute a `count` instead,
which wouldn't join.

Of course, the only time we actually need to perform a join on the eager
loaded values (which would perform a left outer join) is if they're
being referenced in the where clause. This doesn't affect inner joins.

The focus of this change is to make the API more accessible.
References to method and classes should be linked to make it easy to
navigate around.

This patch makes exzessiv use of `rdoc-ref:` to provide more readable
docs. This makes it possible to document `ActiveRecord::Base#save` even
though the method is within a separate module
`ActiveRecord::Persistence`. The goal here is to bring the API closer to
the actual code that you would write.

This commit only deals with Active Record. The other gems will be
updated accordingly but in different commits. The pass through Active
Record is not completely finished yet. A follow up commit will change
the spots I haven't yet had the time to update.

/cc @fxn

ActiveRecord::RecordNotFound modified to store model name, primary_key
and id of the caller model. It allows the catcher of this exception to make
a better decision to what to do with it. For example consider this simple
example:

    class SomeAbstractController < ActionController::Base
      rescue_from ActiveRecord::RecordNotFound, with: :redirect_to_404

      private def redirect_to_404(e)
        return redirect_to(posts_url) if e.model == 'Post'
        raise
      end
    end

After discussing, we've decided it makes more sense to include it. We're
already forwarding every conflicting method to `to_a`, and there's no
conflation of concerns. `Enumerable` has no mutating methods, and it
just allows us to simplify the code. No existing methods will have a
change in behavior. Un-overridden Enumerable methods will simply
delegate to `each`.

[Sean Griffin & bogdan]

do not change the order of the result if the object was already ordered by the user via :order clause

Stems from https://github.com/rails/rails/pull/20105#issuecomment-100900939
where @senny said:

> From my point of view, all the docs (guides, API) are version bound.
> They should describe that version and continue to be available when newer versions are released.
> The cross referencing can be done by the interested user.

Now that master points at Rails 5, we might not need to explain how
things used to work in Rails 3. Or we might… up to you 😁