Skip to main content

# Atomic Increment/Decrement (LCC.kvdb.dict.incr)

## Signature​

    value, meta_or_err = LCC.kvdb.dict.incr(name, key, by?, init?, min?, max?, coerce?, timeout?)

## Parameters​

- name
  String. Dictionary name (non-empty, max `256` bytes).
- key
  String. Key to modify (must be valid UTF-8 and non-empty).
- by
  Integer, optional. Step size; defaults to `1` and can be negative.
- init
  Integer, optional. Initial value when the key is missing; defaults to `0`.
- min
  Integer, optional. Lower bound; results are clamped when below it.
- max
  Integer, optional. Upper bound; results are clamped when above it.
- coerce
  Boolean, optional. When `true`, non-integer existing values are reset to `init`; defaults to `false`.
- timeout
  Number, optional. Request timeout in seconds, default `60`.

## Returns​

- value
  Number. Result after incrementing; `nil` on failure.
- meta_or_err
  Table or string. On success returns metadata:
  - `created`: whether the key was created this time
  - `coerced`: whether coercion happened
  - `clamped`: whether the value was clamped
  - `clamp_reason`: `'min'` or `'max'` when clamped
  - `original_value`: previous numeric value (when one existed)
  - `computed_value`: result before clamping
  - `result_value`: final stored value
    On failure contains the error message.

## Notes​

> Provides a thread-safe atomic counter operation.
> Use `min`/`max` to constrain the range and `coerce` to reset invalid values back to `init`.
> Returns `nil` with an error string when the call fails.

## Example​

    local value, meta = LCC.kvdb.dict.incr("counter", "retry", 1, 0, 0, 5, true)
    if value then
        LCC.log(1, "Retry count", value, meta.clamped and "Reached limit" or "")
    end