From 70c23e2d32db3fdb50c1e54e46e6a59522a93a83 Mon Sep 17 00:00:00 2001 From: Mike Dirolf Date: Thu, 17 Sep 2009 16:45:03 -0400 Subject: [PATCH] deprecate :offset option to find in favor of :skip --- examples/queries.rb | 4 ++-- lib/mongo/collection.rb | 11 ++++++++--- lib/mongo/cursor.rb | 2 +- lib/mongo/query.rb | 3 +-- test/mongo-qa/find1 | 2 +- test/test_collection.rb | 19 ++++++++++++++++++- test/test_cursor.rb | 2 +- 7 files changed, 32 insertions(+), 11 deletions(-) diff --git a/examples/queries.rb b/examples/queries.rb index bab22e4..d9d92ff 100644 --- a/examples/queries.rb +++ b/examples/queries.rb @@ -38,9 +38,9 @@ rows.each { |row| pp row } # 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}}) diff --git a/lib/mongo/collection.rb b/lib/mongo/collection.rb index 3c3ebbb..f4d8fcc 100644 --- a/lib/mongo/collection.rb +++ b/lib/mongo/collection.rb @@ -88,7 +88,8 @@ module Mongo # 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 @@ module Mongo 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 @@ module Mongo 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() diff --git a/lib/mongo/cursor.rb b/lib/mongo/cursor.rb index b1bfac8..2cc08e9 100644 --- a/lib/mongo/cursor.rb +++ b/lib/mongo/cursor.rb @@ -107,7 +107,7 @@ module Mongo # # 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 diff --git a/lib/mongo/query.rb b/lib/mongo/query.rb index baf4cd5..5559367 100644 --- a/lib/mongo/query.rb +++ b/lib/mongo/query.rb @@ -38,8 +38,7 @@ module Mongo # (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 diff --git a/test/mongo-qa/find1 b/test/mongo-qa/find1 index 60569ca..2dc4b15 100644 --- a/test/mongo-qa/find1 +++ b/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'] } diff --git a/test/test_collection.rb b/test/test_collection.rb index 5f6b46e..b237a50 100644 --- a/test/test_collection.rb +++ b/test/test_collection.rb @@ -165,7 +165,7 @@ class TestCollection < Test::Unit::TestCase 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 @@ class TestCollection < Test::Unit::TestCase # 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) diff --git a/test/test_cursor.rb b/test/test_cursor.rb index d36d380..efecd4d 100644 --- a/test/test_cursor.rb +++ b/test/test_cursor.rb @@ -43,7 +43,7 @@ class CursorTest < Test::Unit::TestCase 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()