This method no longer returns an array of all records that
have been removed. Correct documentation to reflect this change.

See issue 14546

CollectionProxy should be able to reuse the behavior (methods) of its parent class,
but with its own state. This change allows CollectionProxy to use the arel object
corresponding to its association's scope.

Need to define #reset on CollectionProxy.

This commit fixes two regressions introduced in cafe31a0 where
newly created finder methods #second, #third, #forth, and #fifth
caused a NoMethodError error on reload associations and where we
were pulling the wrong element out of cached associations.

Examples:

  some_book.authors.reload.second

  # Before
  # => NoMethodError: undefined method 'first' for nil:NilClass

  # After
  # => #<Author id: 2, name: "Sally Second", ...>

  some_book.first.authors.first
  some_book.first.authors.second

  # Before
  # => #<Author id: 1, name: "Freddy First", ...>
  # => #<Author id: 1, name: "Freddy First", ...>

  # After
  # => #<Author id: 1, name: "Freddy First", ...>
  # => #<Author id: 2, name: "Sally Second", ...>

Fixes #13783.

It is needed for activerecord-depecated_finders

This reverts commit dcff027a, reversing
changes made to 3a209398.

According to our guideline, we leave 1 space between `#` and `=>`, so we
want `# =>` instead of `#=>`.

Thanks to @fxn for the suggestion.

[ci skip]

Method `delete_all` should not be invoking callbacks and this
feature was deprecated in Rails 4.0. This is being removed.
`delete_all` will continue to honor the `:dependent` option. However
if `:dependent` value is `:destroy` then the default deletion
strategy for that collection will be applied.

User can also force a deletion strategy by passing parameter to
`delete_all`. For example you can do `@post.comments.delete_all(:nullify)`

The previous implementation was necessary in order to support stuff
like:

    class Post < ActiveRecord::Base
      default_scope where(published: true)
      scope :ordered, order("created_at")
    end

If we didn't evaluate the default scope at the last possible moment
before sending the SQL to the database, it would become impossible to
do:

    Post.unscoped.ordered

This is because the default scope would already be bound up in the
"ordered" scope, and therefore wouldn't be removed by the
"Post.unscoped" part.

In 4.0, we have deprecated all "eager" forms of scopes. So now you must
write:

    class Post < ActiveRecord::Base
      default_scope { where(published: true) }
      scope :ordered, -> { order("created_at") }
    end

This prevents the default scope getting bound up inside the "ordered"
scope, which means we can now have a simpler/better/more natural
implementation of default scoping.

A knock on effect is that some things that didn't work properly now do.
For example it was previously impossible to use #except to remove a part
of the default scope, since the default scope was evaluated after the
call to #except.

Cleaned up rdoc a bit emphasizing that callbacks are called. Also
removed the stress on the fact that records are always removed.

If callbacks return false then records will not be deleted.

This makes the arguments the same as ActiveRecord::QueryMethods::select.

The similarity of `Relation#uniq` to `Array#uniq` is confusing. Since our
Relation API is close to SQL terms I renamed `#uniq` to `#distinct`.

There is no deprecation. `#uniq` and `#uniq!` are aliases and will continue
to work. I also updated the documentation to promote the use of `#distinct`.

Closes #7364.

Collection associations behave similar to Arrays. However there is no
way to prepend records. And to append one should use `<<`. Before this
patch `#append` and `#prepend` did not add the record to the loaded
association.

`#append` now behaves like `<<` and `#prepend` is not defined.

Fixes #8795

Sometimes, on Mac OS X, programmers accidentally press Option+Space
rather than just Space and don’t see the difference. The problem is
that Option+Space writes a non-breaking space (0XA0) rather than a
normal space (0x20).

This commit removes all the non-breaking spaces inadvertently
introduced in the comments of the code.

At present, ActiveRecord::Delegation compiles delegation methods on a
global basis. The compiled methods apply to all subsequent Relation
instances. This creates several problems:

1) After Post.all.recent has been called, User.all.respond_to?(:recent)
   will be true, even if User.all.recent will actually raise an error due
   to no User.recent method existing. (See #8080.)

2) Depending on the AR class, the delegation should do different things.
   For example, if a Post.zip method exists, then Post.all.zip should call
   it. But this will then result in User.zip being called by a subsequent
   User.all.zip, even if User.zip does not exist, when in fact
   User.all.zip should call User.all.to_a.zip. (There are various
   variants of this problem.)

We are creating these compiled delegations in order to avoid method
missing and to avoid repeating logic on each invocation.

One way of handling these issues is to add additional checks in various
places to ensure we're doing the "right thing". However, this makes the
compiled methods signficantly slower. In which case, there's almost no
point in avoiding method_missing at all. (See #8127 for a proposed
solution which takes this approach.)

This is an alternative approach which involves creating a subclass of
ActiveRecord::Relation for each AR class represented. So, with this
patch, Post.all.class != User.all.class. This means that the delegations
are compiled for and only apply to a single AR class. A compiled method
for Post.all will not be invoked from User.all.

This solves the above issues without incurring significant performance
penalties. It's designed to be relatively seamless, however the downside
is a bit of complexity and potentially confusion for a user who thinks
that Post.all and User.all should be instances of the same class.

Benchmark
---------

require 'active_record'
require 'benchmark/ips'

class Post < ActiveRecord::Base
  establish_connection adapter: 'sqlite3', database: ':memory:'
  connection.create_table :posts

  def self.omg
    :omg
  end
end

relation = Post.all

Benchmark.ips do |r|
  r.report('delegation')   { relation.omg }
  r.report('constructing') { Post.all }
end

Before
------

Calculating -------------------------------------
          delegation      4392 i/100ms
        constructing      4780 i/100ms
-------------------------------------------------
          delegation   144235.9 (±27.7%) i/s -     663192 in   5.038075s
        constructing   182015.5 (±21.2%) i/s -     850840 in   5.005364s

After
-----

Calculating -------------------------------------
          delegation      6677 i/100ms
        constructing      6260 i/100ms
-------------------------------------------------
          delegation   166828.2 (±34.2%) i/s -     754501 in   5.001430s
        constructing   116575.5 (±18.6%) i/s -     563400 in   5.036690s

Comments
--------

Bear in mind that the standard deviations in the above are huge, so we
can't compare the numbers too directly. However, we can conclude that
Relation construction has become a little slower (as we'd expect), but
not by a huge huge amount, and we can still construct a large number of
Relations quite quickly.

So that the scope may be a NullRelation and return a result without
executing a query.

Fixes #7928

Fixes #8102.

I couldn't find a nicer way to deal with this than delegate the call to
 #scope, which will be a NullRelation when we want it to be.