increment

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

Increments 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 regardless of the delta argument.

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 incremented above 2^64 - 1 will overflow (wrap around).

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.