From caa25e9fc3862ea036c81d7b7d58101b6bb79cb8 Mon Sep 17 00:00:00 2001
From: schneems <richard.schneeman@gmail.com>
Date: Sat, 28 Jun 2014 14:03:00 -0500
Subject: [ci skip] Consolidate docs for `first`

Add docs for `first` when provided a numerical argument.

Since `first!` behaves exactly the same way but can raise an argument we can consolidate it in the `first` section.
---
 guides/source/active_record_querying.md | 56 +++++++++++++--------------------
 1 file changed, 21 insertions(+), 35 deletions(-)

(limited to 'guides')

diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 69d6205715..0d3a1dc948 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -132,7 +132,7 @@ TIP: The retrieved record may vary depending on the database engine.
 
 #### `first`
 
-`Model.first` finds the first record ordered by the primary key. For example:
+The `first` method finds the first record ordered by the primary key. For example:
 
 ```ruby
 client = Client.first
@@ -145,7 +145,26 @@ The SQL equivalent of the above is:
 SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
 ```
 
-`Model.first` returns `nil` if no matching record is found and no exception will be raised.
+The `first` method returns `nil` if no matching record is found and no exception will be raised.
+
+You can pass in a numerical argument to the `first` method to return up to that number of results. For example
+
+```ruby
+client = Client.first(3)
+# => [
+  #<Client id: 1, first_name: "Lifo">,
+  #<Client id: 2, first_name: "Fifo">,
+  #<Client id: 3, first_name: "Filo">
+]
+```
+
+The SQL equivalent of the above is:
+
+```sql
+SELECT * FROM clients ORDER BY clients.id ASC LIMIT 3
+```
+
+The `first!` method behaves exactly like `first`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
 
 #### `last`
 
@@ -199,23 +218,6 @@ SELECT * FROM clients LIMIT 1
 
 `Model.take!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
 
-#### `first!`
-
-`Model.first!` finds the first record ordered by the primary key. For example:
-
-```ruby
-client = Client.first!
-# => #<Client id: 1, first_name: "Lifo">
-```
-
-The SQL equivalent of the above is:
-
-```sql
-SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
-```
-
-`Model.first!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
-
 #### `last!`
 
 `Model.last!` finds the last record ordered by the primary key. For example:
@@ -287,22 +289,6 @@ The SQL equivalent of the above is:
 SELECT * FROM clients LIMIT 2
 ```
 
-#### first
-
-`Model.first(limit)` finds the first number of records specified by `limit` ordered by primary key:
-
-```ruby
-Client.first(2)
-# => [#<Client id: 1, first_name: "Lifo">,
-      #<Client id: 2, first_name: "Raf">]
-```
-
-The SQL equivalent of the above is:
-
-```sql
-SELECT * FROM clients ORDER BY id ASC LIMIT 2
-```
-
 #### last
 
 `Model.last(limit)` finds the number of records specified by `limit` ordered by primary key in descending order:
-- 
cgit v1.2.3