From cd840c3e3838c2396176ecfc2820c701080ec115 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 12:40:35 -0500 Subject: Add docs to CollectionAssociation#replace --- .../associations/collection_association.rb | 26 +++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 3af5ff3eab..90899b2078 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -15,7 +15,7 @@ module ActiveRecord # # If you need to work on all current children, new and existing records, # +load_target+ and the +loaded+ flag are your friends. - class CollectionAssociation < Association #:nodoc: + class CollectionAssociation < Association # Implements the reader method, e.g. foo.items for Foo.has_many :items def reader(force_reload = false) @@ -298,8 +298,28 @@ module ActiveRecord end end - # Replace this collection with +other_array+ - # This will perform a diff and delete/add only records that have changed. + # 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 + # # => [ #, # ] + # + # other_pets = [Pet.new(name: 'GorbyPuff', type: 'celibrity')] + # + # person.pets.replace(other_pets) + # + # person.pets + # # => [ # ] + # + # 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 def replace(other_array) other_array.each { |val| raise_on_type_mismatch(val) } original_target = load_target.dup -- cgit v1.2.3 From ea1477fb6d000073c340751c62c3d4d305e4d77f Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 15:05:39 -0500 Subject: fix CollectionAssociation#replace docs --- .../lib/active_record/associations/collection_association.rb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 90899b2078..19ca63d8b8 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -306,14 +306,14 @@ module ActiveRecord # end # # person.pets - # # => [ #, # ] + # # => [#] # - # other_pets = [Pet.new(name: 'GorbyPuff', type: 'celibrity')] + # other_pets = [Pet.new(name: 'GorbyPuff', group: 'celebrities'] # # person.pets.replace(other_pets) # # person.pets - # # => [ # ] + # # => [#] # # If the supplied array has an incorrect association type, it raises # an ActiveRecord::AssociationTypeMismatch error: -- cgit v1.2.3 From 3c91c8127050c7abbe091c19052f9813a62b1af7 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 22:43:51 -0500 Subject: add docs to CollectionAssociation#many? --- .../associations/collection_association.rb | 35 +++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 19ca63d8b8..3e29edfe64 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -282,7 +282,40 @@ module ActiveRecord end end - # Returns true if the collection has more than 1 record. Equivalent to collection.size > 1. + # 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 + # # => [ + # # #, + # # #, + # # # + # # ] + # + # person.pets.many? do |pet| + # pet.group == 'dogs' + # end + # # => false + # + # person.pets.many? do |pet| + # pet.group == 'cats' + # end + # # => true def many? if block_given? load_target.many? { |*block_args| yield(*block_args) } -- cgit v1.2.3 From e66c0fc04967a122cfec656e5473a57ab0223183 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 23:20:21 -0500 Subject: add CollectionAssociation hierarchy --- .../lib/active_record/associations/collection_association.rb | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 3e29edfe64..c4ac2c9f77 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -4,7 +4,12 @@ module ActiveRecord # # CollectionAssociation is an abstract class that provides common stuff to # ease the implementation of association proxies that represent - # collections. See the class hierarchy in AssociationProxy. + # collections. See the class hierarchy in AssociationProxy + # + # CollectionAssociation: + # HasAndBelongsToManyAssociation => has_and_belongs_to_many + # HasManyAssociation => has_many + # HasManyThroughAssociation + ThroughAssociation => has_many :through # # You need to be careful with assumptions regarding the target: The proxy # does not fetch records from the database until it needs them, but new @@ -352,7 +357,7 @@ module ActiveRecord # an ActiveRecord::AssociationTypeMismatch error: # # person.pets.replace(["doo", "ggie", "gaga"]) - # #=> ActiveRecord::AssociationTypeMismatch: Pet expected, got String + # # => ActiveRecord::AssociationTypeMismatch: Pet expected, got String def replace(other_array) other_array.each { |val| raise_on_type_mismatch(val) } original_target = load_target.dup -- cgit v1.2.3 From c0c0ef59921a4a8795cd20348afc243cccc4821e Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 23:25:27 -0500 Subject: add more explanation to CollectionAssociation docs --- activerecord/lib/active_record/associations/collection_association.rb | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index c4ac2c9f77..11608a8ec1 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -11,6 +11,10 @@ module ActiveRecord # HasManyAssociation => has_many # HasManyThroughAssociation + ThroughAssociation => has_many :through # + # CollectionAssociation class provides common methods to the collections + # defined by +has_and_belongs_to_many+, +has_many+ and +has_many+ with + # +:through+ association option. + # # You need to be careful with assumptions regarding the target: The proxy # does not fetch records from the database until it needs them, but new # ones created with +build+ are added to the target. So, the target may be -- cgit v1.2.3 From fcc13f46f5f8db2a7010c00bd209d442461e948d Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 23:30:51 -0500 Subject: add example to CollectionAssociation#destroy_all --- .../associations/collection_association.rb | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 11608a8ec1..7c31c8b923 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -4,7 +4,7 @@ module ActiveRecord # # CollectionAssociation is an abstract class that provides common stuff to # ease the implementation of association proxies that represent - # collections. See the class hierarchy in AssociationProxy + # collections. See the class hierarchy in AssociationProxy. # # CollectionAssociation: # HasAndBelongsToManyAssociation => has_and_belongs_to_many @@ -12,7 +12,7 @@ module ActiveRecord # HasManyThroughAssociation + ThroughAssociation => has_many :through # # CollectionAssociation class provides common methods to the collections - # defined by +has_and_belongs_to_many+, +has_many+ and +has_many+ with + # defined by +has_and_belongs_to_many+, +has_many+ or +has_many+ with # +:through+ association option. # # You need to be careful with assumptions regarding the target: The proxy @@ -170,6 +170,17 @@ module ActiveRecord # 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 # => [] + # # See destroy for more info. def destroy_all destroy(load_target).tap do @@ -178,7 +189,7 @@ module ActiveRecord end end - # Calculate sum using SQL, not Enumerable + # Calculate sum using SQL, not Enumerable. def sum(*args) if block_given? scoped.sum(*args) { |*block_args| yield(*block_args) } -- cgit v1.2.3 From 3ef1f9448332d8e73676ceb15e94d5482c75f1d3 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Thu, 17 May 2012 23:39:15 -0500 Subject: fix CollectionAssociation docs --- activerecord/lib/active_record/associations/collection_association.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 7c31c8b923..b00483a421 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -13,7 +13,7 @@ module ActiveRecord # # CollectionAssociation class provides common methods to the collections # defined by +has_and_belongs_to_many+, +has_many+ or +has_many+ with - # +:through+ association option. + # +:through association+ option. # # You need to be careful with assumptions regarding the target: The proxy # does not fetch records from the database until it needs them, but new -- cgit v1.2.3 From 10d375efaa85cbfab11def8ddff7069b18da7064 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 00:22:32 -0500 Subject: add examples to CollectionAssociation#concat --- .../associations/collection_association.rb | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index b00483a421..bfc2058a2c 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -124,8 +124,19 @@ module ActiveRecord create_record(attributes, options, true, &block) end - # 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. + # 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 # => [#, #, #] def concat(*records) load_target if owner.new_record? @@ -151,7 +162,7 @@ module ActiveRecord end end - # Remove all records from this association + # Remove all records from this association. # # See delete for more info. def delete_all -- cgit v1.2.3 From d029d50d48aa90655877749a57f316f6063fccf8 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 01:03:40 -0500 Subject: add docs to CollectionAssociation#any? --- .../associations/collection_association.rb | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index bfc2058a2c..24718cd4b1 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -305,6 +305,36 @@ module ActiveRecord size.zero? end + # 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 + # # => [#] + # + # person.pets.any? do |pet| + # pet.group == 'cats' + # end + # # => false + # + # person.pets.any? do |pet| + # pet.group == 'dogs' + # end + # # => true def any? if block_given? load_target.any? { |*block_args| yield(*block_args) } -- cgit v1.2.3 From bf55f28af159ccfaa0bb8e5e0b52e50e14ede406 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 01:11:37 -0500 Subject: add docs to CollectionAssociation#empty? --- .../associations/collection_association.rb | 35 ++++++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 24718cd4b1..7ee942d153 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -298,9 +298,38 @@ module ActiveRecord load_target.size end - # Equivalent to collection.size.zero?. If the collection has - # not been already loaded and you are going to fetch the records anyway - # it is better to check collection.length.zero?. + # Returns true if the collection is empty. Equivalent to + # collection.size.zero?. If the collection has not been already + # loaded and you are going to fetch the records anyway it is better to + # check collection.length.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 + # + # 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 empty. + # + # person.pets + # # => [#] + # + # person.pets.empty? do |pet| + # pet.group == 'cats' + # end + # # => false + # + # person.pets.empty? do |pet| + # pet.group == 'dogs' + # end + # # => true def empty? size.zero? end -- cgit v1.2.3 From 48acd29adbd86cec54eec6760dd317f4901125aa Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 01:15:41 -0500 Subject: remove incorrect example of CollectionAssociation#empty? --- .../associations/collection_association.rb | 17 ----------------- 1 file changed, 17 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 7ee942d153..9abe648708 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -313,23 +313,6 @@ module ActiveRecord # person.pets.delete_all # person.pets.count # => 0 # person.pets.empty? # => 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 empty. - # - # person.pets - # # => [#] - # - # person.pets.empty? do |pet| - # pet.group == 'cats' - # end - # # => false - # - # person.pets.empty? do |pet| - # pet.group == 'dogs' - # end - # # => true def empty? size.zero? end -- cgit v1.2.3 From 83153c7a36bb8e31cd5cd6e00f1931fe3c22d371 Mon Sep 17 00:00:00 2001 From: Peter Suschlik Date: Fri, 18 May 2012 12:24:19 +0200 Subject: Fix typo. --- activerecord/lib/active_record/core.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/core.rb b/activerecord/lib/active_record/core.rb index b2ed606e5f..f2833fbf3c 100644 --- a/activerecord/lib/active_record/core.rb +++ b/activerecord/lib/active_record/core.rb @@ -127,7 +127,7 @@ module ActiveRecord object.is_a?(self) end - # Returns an instance of Arel::Table loaded with the curent table name. + # Returns an instance of Arel::Table loaded with the current table name. # # class Post < ActiveRecord::Base # scope :published_and_commented, published.and(self.arel_table[:comments_count].gt(0)) -- cgit v1.2.3 From db77b16e4fa1b2b23d4809b6fb34f61920a120df Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 15:06:47 -0500 Subject: add explanation of raising errors when a limit scope is supplied in Relation#delete_all --- activerecord/lib/active_record/relation.rb | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb index 779e052e3c..05ced3299b 100644 --- a/activerecord/lib/active_record/relation.rb +++ b/activerecord/lib/active_record/relation.rb @@ -370,17 +370,12 @@ module ActiveRecord end end - # Deletes the records matching +conditions+ without instantiating the records first, and hence not - # calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that - # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations - # though, in particular :dependent rules defined on associations are not honored. Returns - # the number of rows affected. - # - # ==== Parameters - # - # * +conditions+ - Conditions are specified the same way as with +find+ method. - # - # ==== Example + # Deletes the records matching +conditions+ without instantiating the records + # first, and hence not calling the +destroy+ method nor invoking callbacks. This + # is a single SQL DELETE statement that goes straight to the database, much more + # efficient than +destroy_all+. Be careful with relations though, in particular + # :dependent rules defined on associations are not honored. Returns the + # number of rows affected. # # Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')") # Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else']) @@ -389,6 +384,11 @@ module ActiveRecord # Both calls delete the affected posts all at once with a single DELETE statement. # If you need to destroy dependent associations or call your before_* or # +after_destroy+ callbacks, use the +destroy_all+ method instead. + # + # If a limit scope is supplied, +delete_all+ raises an ActiveRecord error: + # + # Post.limit(100).delete_all + # # => ActiveRecord::ActiveRecordError: delete_all doesn't support limit scope def delete_all(conditions = nil) raise ActiveRecordError.new("delete_all doesn't support limit scope") if self.limit_value -- cgit v1.2.3 From 1b5c775e7a6d5457da6d2fe02e9e72c6788a7373 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 15:27:29 -0500 Subject: move docs from CollectionAssociation to CollectionProxy --- .../associations/collection_association.rb | 114 +--------------- .../active_record/associations/collection_proxy.rb | 143 ++++++++++++++++++++- 2 files changed, 143 insertions(+), 114 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb index 9abe648708..aa354d9009 100644 --- a/activerecord/lib/active_record/associations/collection_association.rb +++ b/activerecord/lib/active_record/associations/collection_association.rb @@ -24,7 +24,7 @@ module ActiveRecord # # If you need to work on all current children, new and existing records, # +load_target+ and the +loaded+ flag are your friends. - class CollectionAssociation < Association + class CollectionAssociation < Association #:nodoc: # Implements the reader method, e.g. foo.items for Foo.has_many :items def reader(force_reload = false) @@ -127,16 +127,6 @@ module ActiveRecord # 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 # => [#, #, #] def concat(*records) load_target if owner.new_record? @@ -181,17 +171,6 @@ module ActiveRecord # 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 # => [] - # # See destroy for more info. def destroy_all destroy(load_target).tap do @@ -302,51 +281,12 @@ module ActiveRecord # collection.size.zero?. If the collection has not been already # loaded and you are going to fetch the records anyway it is better to # check collection.length.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 def empty? size.zero? end # 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 - # # => [#] - # - # person.pets.any? do |pet| - # pet.group == 'cats' - # end - # # => false - # - # person.pets.any? do |pet| - # pet.group == 'dogs' - # end - # # => true def any? if block_given? load_target.any? { |*block_args| yield(*block_args) } @@ -357,38 +297,6 @@ module ActiveRecord # 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 - # # => [ - # # #, - # # #, - # # # - # # ] - # - # person.pets.many? do |pet| - # pet.group == 'dogs' - # end - # # => false - # - # person.pets.many? do |pet| - # pet.group == 'cats' - # end - # # => true def many? if block_given? load_target.many? { |*block_args| yield(*block_args) } @@ -406,26 +314,6 @@ module ActiveRecord # 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 - # # => [#] - # - # other_pets = [Pet.new(name: 'GorbyPuff', group: 'celebrities'] - # - # person.pets.replace(other_pets) - # - # person.pets - # # => [#] - # - # 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 def replace(other_array) other_array.each { |val| raise_on_type_mismatch(val) } original_target = load_target.dup 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 # => [#, #, #] + + ## + # :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 + # # => [#] + # + # other_pets = [Pet.new(name: 'GorbyPuff', group: 'celebrities'] + # + # person.pets.replace(other_pets) + # + # person.pets + # # => [#] + # + # 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 + # # => [#] + # + # 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 + # # => [ + # # #, + # # #, + # # # + # # ] + # + # 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, -- cgit v1.2.3 From 23a98ffbd9b39ee70094ded1671cf1879d0d3591 Mon Sep 17 00:00:00 2001 From: Avi Tzurel Date: Sat, 19 May 2012 00:47:53 +0300 Subject: You can add a custom primary key to a table --- .../active_record/connection_adapters/abstract/schema_statements.rb | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index 62b0f51bb2..40dc105d5e 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -141,6 +141,11 @@ module ActiveRecord # name varchar(80) # ) # + # ====== Add a custom primary key column + # create_table(:objects, :id => false) do |t| + # t.string :slug, :primary => true + # end + # # ====== Do not add a primary key column # create_table(:categories_suppliers, :id => false) do |t| # t.column :category_id, :integer -- cgit v1.2.3 From 5111ec446bedbc8d0ff6ef11de1000047e0edff5 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 18 May 2012 19:28:09 -0500 Subject: add CollectionProxy#include? documentation --- .../lib/active_record/associations/collection_proxy.rb | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 40f59f2c77..0131fa3a5b 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -177,6 +177,19 @@ module ActiveRecord # pet.group == 'cats' # end # # => true + + ## + # :method: include? + # Returns true if the given object is present in the collection. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets # => [#] + # + # person.pets.include?(Pet.find(20)) # => true + # person.pets.include?(Pet.find(21)) # => false delegate :select, :find, :first, :last, :build, :create, :create!, :concat, :replace, :delete_all, :destroy_all, :delete, :destroy, :uniq, -- cgit v1.2.3 From 3f46f73d004eb19616ad9863fefa4c21ef1d76c3 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 19 May 2012 00:21:50 -0500 Subject: add CollectionProxy#clear documentation --- .../active_record/associations/collection_proxy.rb | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 0131fa3a5b..50f9aecd56 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -243,6 +243,32 @@ module ActiveRecord end alias_method :push, :<< + # Removes every object from the collection. This does not destroy + # the objects, it sets their foreign keys to +NULL+. Returns +self+ + # so methods can be chained. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets # => [#] + # person.pets.clear # => [] + # person.pets.size # => 0 + # + # Pet.find(1) # => # + # + # If they are associated with +dependent: :destroy+ option, it deletes + # them directly from the database. + # + # class Person < ActiveRecord::Base + # has_many :pets, dependent: :destroy + # end + # + # person.pets # => [#] + # person.pets.clear # => [] + # person.pets.size # => 0 + # + # Pet.find(2) # => ActiveRecord::RecordNotFound: Couldn't find Pet with id=2 def clear delete_all self -- cgit v1.2.3 From bb887b92f8ed119641d68487cef1b5b34b2518a1 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 19 May 2012 00:37:47 -0500 Subject: add CollectionProxy#<< documentation --- .../active_record/associations/collection_proxy.rb | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 50f9aecd56..54e497fdca 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -238,6 +238,26 @@ module ActiveRecord end alias_method :to_a, :to_ary + # Adds one or more +records+ to the collection by setting their foreign keys + # to the collection‘s primary key. Returns +self+, so several appends may be + # chained together. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets.size # => 0 + # person.pets << Pet.new(name: 'Fancy-Fancy') + # person.pets << [Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo')] + # person.pets.size # => 3 + # + # person.id # => 1 + # person.pets + # # => [ + # # #, + # # #, + # # # + # # ] def <<(*records) proxy_association.concat(records) && self end -- cgit v1.2.3 From 970a1469977690a1396741272049ff76f737fbb1 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 19 May 2012 00:48:43 -0500 Subject: fix CollectionProxy#<< documentation --- activerecord/lib/active_record/associations/collection_proxy.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 54e497fdca..2f6cae50e4 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -239,7 +239,7 @@ module ActiveRecord alias_method :to_a, :to_ary # Adds one or more +records+ to the collection by setting their foreign keys - # to the collection‘s primary key. Returns +self+, so several appends may be + # to the association‘s primary key. Returns +self+, so several appends may be # chained together. # # class Person < ActiveRecord::Base -- cgit v1.2.3 From bc8b7e036515dfa465f6fcf20e42d9950f42762c Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 19 May 2012 01:01:51 -0500 Subject: improve CollectionProxy#concat documentation --- .../active_record/associations/collection_proxy.rb | 25 ++++++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 2f6cae50e4..03cbba8dea 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -38,19 +38,30 @@ module ActiveRecord ## # :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. + # Add one or more records to the collection by setting their foreign keys + # to the association's primary key. Since << flattens its argument list and + # inserts each record, +push+ and +concat+ behave identically. Returns +self+ + # so method calls may be chained. # # 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.size # => 0 + # person.pets.concat(Pet.new(name: 'Fancy-Fancy')) + # person.pets.concat(Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo')) + # person.pets.size # => 3 + # + # person.id # => 1 + # person.pets + # # => [ + # # #, + # # #, + # # # + # # ] # - # person.pets # => [#, #, #] + # person.pets.concat([Pet.new(name: 'Brain'), Pet.new(name: 'Benny')]) + # person.pets.size # => 5 ## # :method: replace -- cgit v1.2.3 From 6c7c997102e328b5132f8076b5c06107ce459494 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 19 May 2012 17:38:44 +0530 Subject: Revert "You can add a custom primary key to a table" This reverts commit 23a98ffbd9b39ee70094ded1671cf1879d0d3591. [ci skip] --- .../active_record/connection_adapters/abstract/schema_statements.rb | 5 ----- 1 file changed, 5 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index 40dc105d5e..62b0f51bb2 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -141,11 +141,6 @@ module ActiveRecord # name varchar(80) # ) # - # ====== Add a custom primary key column - # create_table(:objects, :id => false) do |t| - # t.string :slug, :primary => true - # end - # # ====== Do not add a primary key column # create_table(:categories_suppliers, :id => false) do |t| # t.column :category_id, :integer -- cgit v1.2.3 From 75d71017fdf16f62c7d537788a1a175546457950 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 19 May 2012 08:15:27 -0500 Subject: add CollectionProxy#first documentation --- .../active_record/associations/collection_proxy.rb | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 03cbba8dea..401019e1f3 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -36,6 +36,33 @@ module ActiveRecord class CollectionProxy < Relation delegate :target, :load_target, :loaded?, :to => :@association + ## + # :method: first + # Returns the first record, or the first +n+ records, from the collection. + # If the collection is empty, the first form returns nil, and the second + # form returns an empty array. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets + # # => [ + # # #, + # # #, + # # # + # + # person.pets.first # => # + # person.pets.first(2) + # # => [ + # # #, + # # # + # # ] + # + # another_person_without.pets # => [] + # another_person_without.pets.first # => nil + # another_person_without.pets.first(3) # => [] + ## # :method: concat # Add one or more records to the collection by setting their foreign keys -- cgit v1.2.3 From b0f55c68887930ada279302cceaf10e2ca67de52 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 19 May 2012 08:20:49 -0500 Subject: add CollectionProxy#last documentation --- .../active_record/associations/collection_proxy.rb | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 401019e1f3..a7d7e3a870 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -63,6 +63,33 @@ module ActiveRecord # another_person_without.pets.first # => nil # another_person_without.pets.first(3) # => [] + ## + # :method: last + # Returns the last record, or the last +n+ records, from the collection. + # If the collection is empty, the first form returns nil, and the second + # form returns an empty array. + # + # class Person < ActiveRecord::Base + # has_many :pets + # end + # + # person.pets + # # => [ + # # #, + # # #, + # # # + # + # person.pets.last # => # + # person.pets.last(2) + # # => [ + # # #, + # # # + # # ] + # + # another_person_without.pets # => [] + # another_person_without.pets.last # => nil + # another_person_without.pets.last(3) # => [] + ## # :method: concat # Add one or more records to the collection by setting their foreign keys -- cgit v1.2.3 From 4adfd8e68db88e08ea39c05a14a3375651f058d3 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 19 May 2012 19:33:51 +0530 Subject: copy edits [ci skip] --- .../active_record/associations/collection_proxy.rb | 37 ++++++++++++---------- 1 file changed, 20 insertions(+), 17 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index a7d7e3a870..fa316a8c9d 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -51,8 +51,10 @@ module ActiveRecord # # #, # # #, # # # + # # ] # # person.pets.first # => # + # # person.pets.first(2) # # => [ # # #, @@ -78,8 +80,10 @@ module ActiveRecord # # #, # # #, # # # + # # ] # # person.pets.last # => # + # # person.pets.last(2) # # => [ # # #, @@ -116,7 +120,7 @@ module ActiveRecord # # person.pets.concat([Pet.new(name: 'Brain'), Pet.new(name: 'Benny')]) # person.pets.size # => 5 - + ## # :method: replace # Replace this collection with +other_array+. This will perform a diff @@ -127,17 +131,17 @@ module ActiveRecord # end # # person.pets - # # => [#] + # # => [#] # - # other_pets = [Pet.new(name: 'GorbyPuff', group: 'celebrities'] + # other_pets = [Pet.new(name: 'Puff', group: 'celebrities'] # # person.pets.replace(other_pets) # # person.pets - # # => [#] + # # => [#] # # If the supplied array has an incorrect association type, it raises - # an ActiveRecord::AssociationTypeMismatch error: + # an ActiveRecord::AssociationTypeMismatch error: # # person.pets.replace(["doo", "ggie", "gaga"]) # # => ActiveRecord::AssociationTypeMismatch: Pet expected, got String @@ -156,27 +160,26 @@ module ActiveRecord # # 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.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?+. + # Returns true if the collection is not empty. # # class Person < ActiveRecord::Base # has_many :pets @@ -189,7 +192,7 @@ module ActiveRecord # person.pets.count # => 0 # person.pets.any? # => true # - # Also, you can pass a block to define a criteria. The behaviour + # You can also pass a block to define criteria. The behaviour # is the same, it returns true if the collection based on the # criteria is not empty. # @@ -208,7 +211,7 @@ module ActiveRecord ## # :method: many? - # Returns true if the collection has more than 1 record. + # Returns true if the collection has more than one record. # Equivalent to +collection.size > 1+. # # class Person < ActiveRecord::Base @@ -222,14 +225,14 @@ module ActiveRecord # person.pets.count #=> 2 # person.pets.many? #=> true # - # Also, you can pass a block to define a criteria. The + # You can also pass a block to define criteria. The # behaviour is the same, it returns true if the collection - # based on the criteria has more than 1 record. + # based on the criteria has more than one record. # # person.pets # # => [ - # # #, - # # #, + # # #, + # # #, # # # # # ] # @@ -349,7 +352,7 @@ module ActiveRecord # has_many :pets, dependent: :destroy # end # - # person.pets # => [#] + # person.pets # => [#] # person.pets.clear # => [] # person.pets.size # => 0 # -- cgit v1.2.3