diff options
Diffstat (limited to 'activerecord/lib/active_record/associations/collection_proxy.rb')
| -rw-r--r-- | activerecord/lib/active_record/associations/collection_proxy.rb | 143 |
1 files changed, 142 insertions, 1 deletions
diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index cf4cc98f38..40f59f2c77 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -33,9 +33,150 @@ module ActiveRecord # # is computed directly through SQL and does not trigger by itself the # instantiation of the actual post records. - class CollectionProxy < Relation # :nodoc: + class CollectionProxy < Relation delegate :target, :load_target, :loaded?, :to => :@association + ## + # :method: concat + # Add +records+ to this association. Returns +self+ so method calls may + # be chained. Since << flattens its argument list and inserts each record, + # +push+ and +concat+ behave identically. + # + # class Person < ActiveRecord::Base + # pets :has_many + # end + # + # person.pets << Person.new(name: 'Nemo') + # person.pets.concat(Person.new(name: 'Droopy')) + # person.pets.push(Person.new(name: 'Ren')) + # + # person.pets # => [#<Pet name: "Nemo">, #<Pet name: "Droopy">, #<Pet name: "Ren">] + + ## + # :method: replace + # Replace this collection with +other_array+. This will perform a diff + # and delete/add only records that have changed. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets + # # => [#<Pet id: 1, name: "Wy", group: "cats", person_id: 1>] + # + # other_pets = [Pet.new(name: 'GorbyPuff', group: 'celebrities'] + # + # person.pets.replace(other_pets) + # + # person.pets + # # => [#<Pet id: 2, name: "GorbyPuff", group: "celebrities", person_id: 1>] + # + # If the supplied array has an incorrect association type, it raises + # an ActiveRecord::AssociationTypeMismatch error: + # + # person.pets.replace(["doo", "ggie", "gaga"]) + # # => ActiveRecord::AssociationTypeMismatch: Pet expected, got String + + ## + # :method: destroy_all + # Destroy all the records from this association. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets.size # => 3 + # + # person.pets.destroy_all + # + # person.pets.size # => 0 + # person.pets # => [] + + ## + # :method: empty? + # Returns true if the collection is empty. + # Equivalent to +size.zero?+. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets.count # => 1 + # person.pets.empty? # => false + # + # person.pets.delete_all + # person.pets.count # => 0 + # person.pets.empty? # => true + + ## + # :method: any? + # Returns true if the collections is not empty. + # Equivalent to +!collection.empty?+. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets.count # => 0 + # person.pets.any? # => false + # + # person.pets << Pet.new(name: 'Snoop') + # person.pets.count # => 0 + # person.pets.any? # => true + # + # Also, you can pass a block to define a criteria. The behaviour + # is the same, it returns true if the collection based on the + # criteria is not empty. + # + # person.pets + # # => [#<Pet name: "Snoop", group: "dogs">] + # + # person.pets.any? do |pet| + # pet.group == 'cats' + # end + # # => false + # + # person.pets.any? do |pet| + # pet.group == 'dogs' + # end + # # => true + + ## + # :method: many? + # Returns true if the collection has more than 1 record. + # Equivalent to +collection.size > 1+. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets.count #=> 1 + # person.pets.many? #=> false + # + # person.pets << Pet.new(name: 'Snoopy') + # person.pets.count #=> 2 + # person.pets.many? #=> true + # + # Also, you can pass a block to define a criteria. The + # behaviour is the same, it returns true if the collection + # based on the criteria has more than 1 record. + # + # person.pets + # # => [ + # # #<Pet name: "GorbyPuff", group: "cats">, + # # #<Pet name: "Wy", group: "cats">, + # # #<Pet name: "Snoop", group: "dogs"> + # # ] + # + # person.pets.many? do |pet| + # pet.group == 'dogs' + # end + # # => false + # + # person.pets.many? do |pet| + # pet.group == 'cats' + # end + # # => true delegate :select, :find, :first, :last, :build, :create, :create!, :concat, :replace, :delete_all, :destroy_all, :delete, :destroy, :uniq, |