The increment methods enable you to increase a given stored integer value. These are the incremental equivalent of the decrement operations and work on the same basis; updating the value of a key if it can be parsed to an integer. The update operation occurs on the server and is provided at the protocol level. This simplifies what would otherwise be a two-stage get and set operation.
| API Call | object.increment(key [, offset ] [, ruby-incr-decr-options ]) | ||
| Asynchronous | no | ||
| Description | Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value. | ||
| Returns | fixnum (
Value for a given key. A fixed number
) | ||
| Arguments | |||
string key | Document ID used to identify the value | ||
offset | Integer offset value to increment/decrement (default 1) | ||
hash ruby-incr-decr-options | Hash of options containing key/value pairs | ||
| Structure definition: | |||
:create (boolean) | :create | ||
| Default is false. If set to true, it will initialize the key with zero value and zero flags (use :initial option to set another initial value). Note: this will not increment or decrement the missing value once it is initialized. | |||
:initial (fixnum) | :create | ||
| Default is 0. Can be an integer (up to 64 bits) for missing key initialization. This option automatically implies the :create option is true, regardless of the setting. | |||
:ttl (int) | :ttl (Expiration) | ||
| Time for document to exist in server before it is automatically destroyed. This option symbol is :ttl and the value can be any number representing seconds. | |||
:extended (boolean) | :extended | ||
| Default is false. If set to true, the operation will return an array, [value, cas], otherwise it returns just the value. | |||
The first form of the incr method accepts
the keyname and offset (increment) value to be used when
increasing the server-side integer. For example, to increment the
server integer dlcounter by 5:
couchbase.set("counter", 10) couchbase.incr("counter", 5) couchbase.get("counter") #=> 15
The second form of the incr method
supports the use of a default value which will be used to set the
corresponding key if that value does already exist in the
database. If the key exists, the default value is ignored and the
value is incremented with the provided offset value. This can be
used in situations where you are recording a counter value but do
not know whether the key exists at the point of storage.
For example, if the key counter does not exist,
the following fragment will return 1000:
counter = couchbase.incr("counter", 1, :initial => 1000); #=> 1000The following demonstrates different options available when using increment and the output they produce:
#increment key by one (default) c.incr("foo") #increment by 50 c.incr("foo", 50) #increment key or initialize with zero c.incr("foo", :create => true) #increment key or initialize with 3 c.incr("foo", 50, :initial => 3) #increment key and get CAS value val, cas = c.incr("foo", :extended => true) #integer overflow from incrementing signed number c.set("foo", -100) c.get("foo") #=> -100 c.incr("foo") #=> 18446744073709551517 #asynchronous use of increment c.run do c.incr("foo") do |ret| ret.operation #=> :increment ret.success? #=> true ret.key #=> "foo" ret.value ret.cas end end