Added Collection#find_first.

lib/mongo/collection.rb

@@ -65,6 +65,14 @@ module XGen
           @db.query(self, Query.new(selector, fields, offset, limit, sort, hint))
         end
 
+        # Find the first record that matches +selector+. See #find.
+        def find_first(selector={}, options={})
+          cursor = find(selector, options)
+          obj = cursor.next_object
+          cursor.close
+          obj
+        end
+
         # Insert +objects+, which are hashes. "<<" is aliased to this method.
         # Returns either the single inserted object or a new array containing
         # +objects+. The object(s) may have been modified by the database's PK

tests/mongo-qa/stress1

@@ -22,9 +22,7 @@ n1.times { |i|
 puts
 
 n2.times { |i|
-  cursor = c.find({:id => i})
-  x = cursor.next_object
-  cursor.close
+  x = c.find_first({:id => i})
   x['subarray'] = "foo#{i}"
   p x
   c.modify({:id => i}, x)

tests/test_db.rb

@@ -67,14 +67,14 @@ class DBTest < Test::Unit::TestCase
 
     # new id gets added to returned object
     obj = coll.insert('name' => 'Fred', 'age' => 42)
-    row = coll.find({'name' => 'Fred'}, :limit => 1).next_object
+    row = coll.find_first({'name' => 'Fred'}, :limit => 1)
     oid = row['_id']
     assert_not_nil oid
     assert_equal obj, row
 
     oid = XGen::Mongo::Driver::ObjectID.new
     obj = coll.insert('_id' => oid, 'name' => 'Barney', 'age' => 41)
-    row = coll.find({'name' => 'Barney'}, :limit => 1).next_object
+    row = coll.find_first({'name' => 'Barney'}, :limit => 1)
     db_oid = row['_id']
     assert_equal oid, db_oid
     assert_equal obj, row

tests/test_db_api.rb

@@ -216,6 +216,18 @@ class DBAPITest < Test::Unit::TestCase
     assert_equal 4, docs.size
   end
 
+  def test_find_first
+    x = @@coll.find_first('a' => 1)
+    assert_not_nil x
+    assert_equal 1, x['a']
+  end
+
+  def test_find_first_no_records
+    @@coll.clear
+    x = @@coll.find_first('a' => 1)
+    assert_nil x
+  end
+
   def test_drop_collection
     assert @@db.drop_collection(@@coll.name), "drop of collection #{@@coll.name} failed"
     assert !@@db.collection_names.include?(@@coll_full_name)