Permalink
Browse files

Improve docs for AR Relation

  • Loading branch information...
1 parent 5edbeb0 commit 2c050e1808b996e6a0ff2e26981087d8c080fc48 @oscardelben oscardelben committed Jul 17, 2012
Showing with 19 additions and 7 deletions.
  1. +19 −7 activerecord/lib/active_record/relation.rb
@@ -184,6 +184,7 @@ def explain
exec_explain(queries)
end
+ # Converts relation objects to Array.
def to_a
# We monitor here the entire execution rather than individual SELECTs
# because from the point of view of the user fetching the records of a
@@ -242,6 +243,7 @@ def empty?
c.respond_to?(:zero?) ? c.zero? : c.empty?
end
+ # Returns true if there are any records.
def any?
if block_given?
to_a.any? { |*block_args| yield(*block_args) }
@@ -250,6 +252,7 @@ def any?
end
end
+ # Returns true if there are more than one records.
def many?
if block_given?
to_a.many? { |*block_args| yield(*block_args) }
@@ -283,17 +286,14 @@ def scoping
# ==== Parameters
#
# * +updates+ - A string, array, or hash representing the SET part of an SQL statement.
- # * +conditions+ - A string, array, or hash representing the WHERE part of an SQL statement.
- # See conditions in the intro.
- # * +options+ - Additional options are <tt>:limit</tt> and <tt>:order</tt>, see the examples for usage.
#
# ==== Examples
#
# # Update all customers with the given attributes
- # Customer.update_all :wants_email => true
+ # Customer.update_all wants_email: true
#
# # Update all books with 'Rails' in their title
- # Book.where('title LIKE ?', '%Rails%').update_all(:author => 'David')
+ # Book.where('title LIKE ?', '%Rails%').update_all(author: 'David')
#
# # Update all books that match conditions, but limit it to 5 ordered by date
# Book.where('title LIKE ?', '%Rails%').order(:created_at).limit(5).update_all(:author => 'David')
@@ -326,7 +326,7 @@ def update_all(updates)
# ==== Examples
#
# # Updates one record
- # Person.update(15, :user_name => 'Samuel', :group => 'expert')
+ # Person.update(15, user_name: 'Samuel', group: 'expert')
#
# # Updates multiple records
# people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } }
@@ -366,7 +366,7 @@ def update(id, attributes)
# ==== Examples
#
# Person.destroy_all("last_login < '2004-04-04'")
- # Person.destroy_all(:status => "inactive")
+ # Person.destroy_all(status: "inactive")
# Person.where(:age => 0..18).destroy_all
def destroy_all(conditions = nil)
if conditions
@@ -468,6 +468,7 @@ def delete(id_or_array)
where(primary_key => id_or_array).delete_all
end
+ # Forces reloading of relation.
def reload
reset
to_a # force reload
@@ -481,10 +482,18 @@ def reset
self
end
+ # Returns sql statement for the relation.
+ #
+ # Users.where(name: 'Oscar').to_sql
+ # # => SELECT "users".* FROM "users" WHERE "users"."name" = 'Oscar'
def to_sql
@to_sql ||= klass.connection.to_sql(arel, bind_values.dup)
end
+ # Returns an hash of where conditions
+ #
+ # Users.where(name: 'Oscar').to_sql
+ # # => {:name=>"oscar"}
def where_values_hash
equalities = with_default_scope.where_values.grep(Arel::Nodes::Equality).find_all { |node|
node.left.relation.name == table_name
@@ -502,6 +511,7 @@ def scope_for_create
@scope_for_create ||= where_values_hash.merge(create_with_value)
end
+ # Returns true if relation needs eager loading.
def eager_loading?
@should_eager_load ||=
eager_load_values.any? ||
@@ -516,6 +526,7 @@ def joined_includes_values
includes_values & joins_values
end
+ # Compares two relations for equality.
def ==(other)
case other
when Relation
@@ -539,6 +550,7 @@ def with_default_scope #:nodoc:
end
end
+ # Returns true if relation is blank>
def blank?
to_a.blank?
end

0 comments on commit 2c050e1

Please sign in to comment.