Merge branch 'master' of git://github.com/rails/rails

1 files changed, 165 insertions, 7 deletions

diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index decde50427..c9fff15199 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -8,7 +8,7 @@ module ActiveRecord
     include FinderMethods, Calculations, SpawnMethods, QueryMethods
 
     delegate :length, :collect, :map, :each, :all?, :include?, :to => :to_a
-    delegate :insert, :update, :to => :arel
+    delegate :insert, :to => :arel
 
     attr_reader :table, :klass
 
@@ -80,19 +80,177 @@ module ActiveRecord
       if block_given?
         to_a.many? { |*block_args| yield(*block_args) }
       else
-        arel.send(:taken).present? ? to_a.many? : size > 1
+        @limit_value.present? ? to_a.many? : size > 1
       end
     end
 
-    def destroy_all
-      to_a.each {|object| object.destroy}
-      reset
+    # Updates all records with details given if they match a set of conditions supplied, limits and order can
+    # also be supplied. This method constructs a single SQL UPDATE statement and sends it straight to the
+    # database. It does not instantiate the involved models and it does not trigger Active Record callbacks
+    # or validations.
+    #
+    # ==== 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
+    #
+    #   # Update all books with 'Rails' in their title
+    #   Book.update_all "author = 'David'", "title LIKE '%Rails%'"
+    #
+    #   # Update all avatars migrated more than a week ago
+    #   Avatar.update_all ['migrated_at = ?', Time.now.utc], ['migrated_at > ?', 1.week.ago]
+    #
+    #   # Update all books that match our conditions, but limit it to 5 ordered by date
+    #   Book.update_all "author = 'David'", "title LIKE '%Rails%'", :order => 'created_at', :limit => 5
+    def update_all(updates, conditions = nil, options = {})
+      if conditions || options.present?
+        where(conditions).apply_finder_options(options.slice(:limit, :order)).update_all(updates)
+      else
+        # Apply limit and order only if they're both present
+        if @limit_value.present? == @order_values.present?
+          arel.update(@klass.send(:sanitize_sql_for_assignment, updates))
+        else
+          except(:limit, :order).update_all(updates)
+        end
+      end
+    end
+
+    # Updates an object (or multiple objects) and saves it to the database, if validations pass.
+    # The resulting object is returned whether the object was saved successfully to the database or not.
+    #
+    # ==== Parameters
+    #
+    # * +id+ - This should be the id or an array of ids to be updated.
+    # * +attributes+ - This should be a hash of attributes to be set on the object, or an array of hashes.
+    #
+    # ==== Examples
+    #
+    #   # Updating one record:
+    #   Person.update(15, :user_name => 'Samuel', :group => 'expert')
+    #
+    #   # Updating multiple records:
+    #   people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } }
+    #   Person.update(people.keys, people.values)
+    def update(id, attributes)
+      if id.is_a?(Array)
+        idx = -1
+        id.collect { |one_id| idx += 1; update(one_id, attributes[idx]) }
+      else
+        object = find(id)
+        object.update_attributes(attributes)
+        object
+      end
+    end
+
+    # Destroys the records matching +conditions+ by instantiating each
+    # record and calling its +destroy+ method. Each object's callbacks are
+    # executed (including <tt>:dependent</tt> association options and
+    # +before_destroy+/+after_destroy+ Observer methods). Returns the
+    # collection of objects that were destroyed; each will be frozen, to
+    # reflect that no changes should be made (since they can't be
+    # persisted).
+    #
+    # Note: Instantiation, callback execution, and deletion of each
+    # record can be time consuming when you're removing many records at
+    # once. It generates at least one SQL +DELETE+ query per record (or
+    # possibly more, to enforce your callbacks). If you want to delete many
+    # rows quickly, without concern for their associations or callbacks, use
+    # +delete_all+ instead.
+    #
+    # ==== Parameters
+    #
+    # * +conditions+ - A string, array, or hash that specifies which records
+    #   to destroy. If omitted, all records are destroyed. See the
+    #   Conditions section in the introduction to ActiveRecord::Base for
+    #   more information.
+    #
+    # ==== Examples
+    #
+    #   Person.destroy_all("last_login < '2004-04-04'")
+    #   Person.destroy_all(:status => "inactive")
+    def destroy_all(conditions = nil)
+      if conditions
+        where(conditions).destroy_all
+      else
+        to_a.each {|object| object.destroy}
+        reset
+      end
+    end
+
+    # Destroy an object (or multiple objects) that has the given id, the object is instantiated first,
+    # therefore all callbacks and filters are fired off before the object is deleted.  This method is
+    # less efficient than ActiveRecord#delete but allows cleanup methods and other actions to be run.
+    #
+    # This essentially finds the object (or multiple objects) with the given id, creates a new object
+    # from the attributes, and then calls destroy on it.
+    #
+    # ==== Parameters
+    #
+    # * +id+ - Can be either an Integer or an Array of Integers.
+    #
+    # ==== Examples
+    #
+    #   # Destroy a single object
+    #   Todo.destroy(1)
+    #
+    #   # Destroy multiple objects
+    #   todos = [1,2,3]
+    #   Todo.destroy(todos)
+    def destroy(id)
+      if id.is_a?(Array)
+        id.map { |one_id| destroy(one_id) }
+      else
+        find(id).destroy
+      end
     end
 
-    def delete_all
-      arel.delete.tap { reset }
+    # 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 <tt>:dependent</tt> 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
+    #
+    #   Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
+    #   Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
+    #
+    # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent
+    # associations or call your <tt>before_*</tt> or +after_destroy+ callbacks, use the +destroy_all+ method instead.
+    def delete_all(conditions = nil)
+      conditions ? where(conditions).delete_all : arel.delete.tap { reset }
     end
 
+    # Deletes the row with a primary key matching the +id+ argument, using a
+    # SQL +DELETE+ statement, and returns the number of rows deleted. Active
+    # Record objects are not instantiated, so the object's callbacks are not
+    # executed, including any <tt>:dependent</tt> association options or
+    # Observer methods.
+    #
+    # You can delete multiple rows at once by passing an Array of <tt>id</tt>s.
+    #
+    # Note: Although it is often much faster than the alternative,
+    # <tt>#destroy</tt>, skipping callbacks might bypass business logic in
+    # your application that ensures referential integrity or performs other
+    # essential jobs.
+    #
+    # ==== Examples
+    #
+    #   # Delete a single row
+    #   Todo.delete(1)
+    #
+    #   # Delete multiple rows
+    #   Todo.delete([2,3,4])
     def delete(id_or_array)
       where(@klass.primary_key => id_or_array).delete_all
     end