deprecate :offset option to find in favor of :skip

Author: Mike Dirolf

examples/queries.rb

@@ -38,9 +38,9 @@
 # records we find.
 coll.find('a' => 1)
 
-# Find records sort by 'a', offset 1, limit 2 records.
+# Find records sort by 'a', skip 1, limit 2 records.
 # Sort can be single name, array, or hash.
-coll.find({}, {:offset => 1, :limit => 2, :sort => 'a'})
+coll.find({}, {:skip => 1, :limit => 2, :sort => 'a'})
 
 # Find all records with 'a' > 1. There is also $lt, $gte, and $lte.
 coll.find({'a' => {'$gt' => 1}})

lib/mongo/collection.rb

@@ -88,7 +88,8 @@ def hint=(hint)
     #            set ("_id" will always be included). By limiting results
     #            to a certain subset of fields you can cut down on network
     #            traffic and decoding time.
-    # :offset :: Start at this record when returning records
+    # :skip :: Number of documents to omit (from the start of the result set)
+    #          when returning the results
     # :limit :: Maximum number of records to return
     # :sort :: Either hash of field names as keys and 1/-1 as values; 1 ==
     #          ascending, -1 == descending, or array of field names (all
@@ -102,7 +103,11 @@ def hint=(hint)
     def find(selector={}, options={})
       fields = options.delete(:fields)
       fields = ["_id"] if fields && fields.empty?
-      offset = options.delete(:offset) || 0
+      skip = options.delete(:offset) || nil
+      if !skip.nil?
+        warn "the :offset option to find is deprecated and will be removed. please use :skip instead"
+      end
+      skip = options.delete(:skip) || skip || 0
       limit = options.delete(:limit) || 0
       sort = options.delete(:sort)
       hint = options.delete(:hint)
@@ -114,7 +119,7 @@ def find(selector={}, options={})
       end
       raise RuntimeError, "Unknown options [#{options.inspect}]" unless options.empty?
 
-      cursor = @db.query(self, Query.new(selector, fields, offset, limit, sort, hint, snapshot))
+      cursor = @db.query(self, Query.new(selector, fields, skip, limit, sort, hint, snapshot))
       if block_given?
         yield cursor
         cursor.close()

lib/mongo/cursor.rb

@@ -107,7 +107,7 @@ def limit(number_to_return)
     #
     # Raises InvalidOperation if this cursor has already been used.
     #
-    # This method overrides any offset specified in the Collection#find method,
+    # This method overrides any skip specified in the Collection#find method,
     # and only the last skip applied has an effect.
     def skip(number_to_skip)
       check_modifiable

lib/mongo/query.rb

@@ -38,8 +38,7 @@ class Query
     #                  (Called :fields in calls to Collection#find.)
     #
     # number_to_skip :: Number of records to skip before returning
-    #                   records. (Called :offset in calls to
-    #                   Collection#find.) Default is 0.
+    #                   records. Default is 0.
     #
     # number_to_return :: Max number of records to return. (Called :limit
     #                     in calls to Collection#find.) Default is 0 (all

test/mongo-qa/find1

@@ -11,5 +11,5 @@ if $DEBUG
   (5..15).each { |i| c.insert(:x => 2, :y => i, :z => (i+64).chr) }
 end
 
-cursor = db.collection('c').find({'x' => 1}, :sort => 'y', :offset => 20, :limit => 10)
+cursor = db.collection('c').find({'x' => 1}, :sort => 'y', :skip => 20, :limit => 10)
 cursor.each { |row| puts row['z'] }

test/test_collection.rb

@@ -165,7 +165,7 @@ def test_optional_find_block
     assert_equal 1, x
 
     i = 0
-    @@test.find({}, :offset => 5) do |cursor|
+    @@test.find({}, :skip => 5) do |cursor|
       cursor.each do |doc|
         i = i + 1
       end
@@ -199,6 +199,23 @@ def test_save_symbol_find_string
     # assert_equal :mike, @@test.find_one("foo" => "mike")["foo"]
   end
 
+  def test_limit_and_skip
+    10.times do |i|
+      @@test.save(:foo => i)
+    end
+
+    # TODO remove test for deprecated :offset option
+    assert_equal 5, @@test.find({}, :offset => 5).next_object()["foo"]
+
+    assert_equal 5, @@test.find({}, :skip => 5).next_object()["foo"]
+    assert_equal nil, @@test.find({}, :skip => 10).next_object()
+
+    assert_equal 5, @@test.find({}, :limit => 5).to_a.length
+
+    assert_equal 3, @@test.find({}, :skip => 3, :limit => 5).next_object()["foo"]
+    assert_equal 5, @@test.find({}, :skip => 3, :limit => 5).to_a.length
+  end
+
   def test_group_with_scope
     @@test.save("a" => 1)
     @@test.save("b" => 1)

test/test_cursor.rb

@@ -43,7 +43,7 @@ def test_count
     assert_equal 10, @@coll.find().count()
     assert_kind_of Integer, @@coll.find().count()
     assert_equal 10, @@coll.find({}, :limit => 5).count()
-    assert_equal 10, @@coll.find({}, :offset => 5).count()
+    assert_equal 10, @@coll.find({}, :skip => 5).count()
 
     assert_equal 1, @@coll.find({"x" => 1}).count()
     assert_equal 5, @@coll.find({"x" => {"$lt" => 5}}).count()