decrement

suspend fun decrement(id: String, common: CommonOptions = CommonOptions.Default, durability: Durability = Durability.disabled(), expiry: Expiry = Expiry.none(), delta: ULong, initialValue: ULong?): CounterResult

Decrements a counter document and returns the new value.

This operation is atomic with respect to a single Couchbase Server cluster, but not between clusters when Cross-Datacenter Replication (XDCR) is used.

If the counter document does not exist, the behavior depends on the initialValue argument. If null, DocumentNotFoundException is thrown. Otherwise the document is created with the initial value and this initial value is returned and the delta argument is ignored.

The content of a counter document is a single JSON integer with a minimum value of zero and a maximum value of 2^64 - 1.

A counter decremented below zero will reset to zero.

Counter values above 2^53 - 1 may have interoperability issues with languages that store all numbers as floating point values.

Parameters

initialValue

if the counter document does not exist, it will be created with this value and this value will be returned, ignoring delta. If null and the document does not exist, DocumentNotFoundException is thrown.

delta

the number to add to the counter. A value of zero returns the current value of the counter. Ignored if the counter document does not already exist, in which case the returned value is determined by initialValue.

expiry

The expiry to assign to the counter if the document does not already exist. If the document already exists, this argument is ignored and the initial expiry is preserved.

durability

The durability requirement for the document update.