Permalink
Browse files

add CollectionProxy#length documentation

  • Loading branch information...
Francesco Rodriguez
Francesco Rodriguez committed May 22, 2012
1 parent f539d98 commit eb2c0a4f712b015bf6886286efd6e5b2eeaf54aa
Showing with 37 additions and 5 deletions.
  1. +37 −5 activerecord/lib/active_record/associations/collection_proxy.rb
@@ -540,20 +540,52 @@ class CollectionProxy < Relation
# has_many :pets
# end
#
- # # This will execute:
- # # SELECT COUNT(*) FROM "pets" WHERE "pets"."person_id" = ? [["person_id", 1]]
# person.pets.size # => 3
+ # # Executes:
+ # #
+ # # SELECT COUNT(*)
+ # # FROM "pets"
+ # # WHERE "pets"."person_id" = 1
#
- # person.pets
+ # person.pets # This will execute a SELECT * FROM query
# # => [
# # #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
# # #<Pet id: 2, name: "Spook", person_id: 1>,
# # #<Pet id: 3, name: "Choo-Choo", person_id: 1>
# # ]
#
- # # Because the collection is already loaded, this will behave like
- # <tt>collection.size</tt> and no SQL count query is executed.
# person.pets.size # => 3
+ # # Because the collection is already loaded, this will behave like
+ # # collection.size and no SQL count query is executed.
+
+ ##
+ # :method: length
+ #
+ # Returns the size of the collection calling +size+ on the target.
+ # If the collection has been already loaded +length+ and +size+ are
+ # equivalent. If not and you are going to need the records anyway this
+ # method will take one less query because loads the collection. Otherwise
+ # +size+ is more efficient.
+ #
+ # class Person < ActiveRecord::Base
+ # has_many :pets
+ # end
+ #
+ # person.pets.length # => 3
+ # # Executes:
+ # #
+ # # SELECT "pets".*
+ # #  FROM "pets"
+ # # WHERE "pets"."person_id" = 1
+ #
+ # # Because the collection is loaded, you can
+ # # call the collection without execute a query:
+ # person.pets
+ # # => [
+ # # #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+ # # #<Pet id: 2, name: "Spook", person_id: 1>,
+ # # #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+ # # ]
##
# :method: empty?

0 comments on commit eb2c0a4

Please sign in to comment.