Module: Couchbase::Operations::Arithmetic

Defined in:: lib/couchbase/operations/arithmetic.rb

Instance Method Summary collapse

#decr(key, delta = 1, options = {}) {|ret| ... } ⇒ Fixnum (also: #decrement)

Decrement the value of an existing numeric key.
#incr(key, delta = 1, options = {}) {|ret| ... } ⇒ Fixnum (also: #increment)

Increment the value of an existing numeric key.

Instance Method Details

#decr(key, delta = 1, options = {}) {|ret| ... } ⇒ `Fixnum` Also known as: decrement

Note:

that server values stored and transmitted as unsigned numbers, therefore if you try to decrement negative or zero key, you will always get zero.

Decrement the value of an existing numeric key

The decrement methods reduce the value of a given key if the corresponding value can be parsed to an integer value. These operations are provided at a protocol level to eliminate the need to get, update, and reset a simple integer value in the database. It supports the use of an explicit offset value that will be used to reduce the stored value in the database.

Returns the actual value of the key.

Examples:

Decrement key by one

c.decr("foo")

Decrement key by 50

c.decr("foo", 50)

Decrement key by one OR initialize with zero

c.decr("foo", :create => true)   #=> will return old-1 or 0

Decrement key by one OR initialize with three

c.decr("foo", 50, :initial => 3) #=> will return old-50 or 3

Decrement key and get its CAS value

val, cas = c.decr("foo", :extended => true)

Decrementing zero

c.set("foo", 0)
c.decrement("foo", 100500)   #=> 0

Decrementing negative value

c.set("foo", -100)
c.decrement("foo", 100500)   #=> 0

Asynchronous invocation

c.run do
  c.decr("foo") do |ret|
    ret.operation   #=> :decrement
    ret.success?    #=> true
    ret.key         #=> "foo"
    ret.value
    ret.cas
  end
end

Parameters:

key (String, Symbol) —

Key used to reference the value.
delta (Fixnum) (defaults to: 1) —

Integer (up to 64 bits) value to decrement
options (Hash) (defaults to: {}) —

Options for operation.

Options Hash (options):

:create (true, false) — default: 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: it won’t decrement the missing value.
:initial (Fixnum) — default: 0 —

Integer (up to 64 bits) value for missing key initialization. This option imply :create option is true.
:ttl (Fixnum) — default: self.default_ttl —

Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). This option ignored for existent keys.
:extended (true, false) — default: false —

If set to true, the operation will return tuple [value, cas], otherwise (by default) it returns just value.

Yield Parameters:

ret (Result) —

the result of operation in asynchronous mode (valid attributes: error, operation, key, value, cas).

Returns:

(Fixnum) —

the actual value of the key.

Raises:

(Couchbase::Error::NotFound) —

if key is missing and :create option isn’t true.
(Couchbase::Error::DeltaBadval) —

if the key contains non-numeric value
(Couchbase::Error::Connect) —

if connection closed (see Bucket#reconnect)
(ArgumentError) —

when passing the block in synchronous mode

Since:

1.0.0

# File 'lib/couchbase/operations/arithmetic.rb', line 191

def decr(*args)
  sync_block_error if !async? && block_given?
  do_arithmetic(:decr, *args)
end

#incr(key, delta = 1, options = {}) {|ret| ... } ⇒ `Fixnum` Also known as: increment

Note:

that server values stored and transmitted as unsigned numbers, therefore if you try to store negative number and then increment or decrement it will cause overflow. (see “Integer overflow” example below)

Increment the value of an existing numeric key

The increment methods allow 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.

Returns the actual value of the key.

Examples:

Increment key by one

c.incr("foo")

Increment key by 50

c.incr("foo", 50)

Increment key by one OR initialize with zero

c.incr("foo", :create => true)   #=> will return old+1 or 0

Increment key by one OR initialize with three

c.incr("foo", 50, :initial => 3) #=> will return old+50 or 3

Increment key and get its CAS value

val, cas = c.incr("foo", :extended => true)

Integer overflow

c.set("foo", -100)
c.get("foo")           #=> -100
c.incr("foo")          #=> 18446744073709551517