跳到主要内容

# 原子自增/自减 (LCC.kvdb.dict.incr)

## 声明​

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

## 参数​

- name
  字符串型，词典名称（非空，最长 `256` 字节）
- key
  字符串型，键名（必须为合法 UTF-8，且非空）
- by
  整数型，可选；增减步长，默认 `1`，可为负数
- init
  整数型，可选；键不存在时的初始值，默认 `0`
- min
  整数型，可选；结果下限，超出时会被钳制
- max
  整数型，可选；结果上限，超出时会被钳制
- coerce
  布尔型，可选；为 `true` 时遇到非整数旧值会强制重置为 `init`，默认 `false`
- timeout
  数值型，可选；请求超时时间（秒），默认 `60`

## 返回值​

- value
  数值型，自增后的结果；失败时为 `nil`
- meta_or_err
  表类型或字符串。成功时返回元信息表：
  - `created`：布尔型，本次是否新建键
  - `coerced`：布尔型，是否触发类型强制
  - `clamped`：布尔型，结果是否被钳制
  - `clamp_reason`：字符串，钳制原因（`min`/`max`）
  - `original_value`：数值型，旧值（若存在）
  - `computed_value`：数值型，按步长计算后的值
  - `result_value`：数值型，最终写入值 失败时返回错误描述字符串

## 说明​

> 线程安全的原子计数器操作。
> 通过 `min`/`max` 可以限制结果区间，`coerce` 用于将非法旧值重置为 `init`。
> 调用失败时返回 `nil, 错误信息`。

## 示例​

    local value, meta = LCC.kvdb.dict.incr("计数器", "重试次数", 1, 0, 0, 5, true)
    if value then
        LCC.log(1, "当前重试次数", value, meta.clamped and "已达上限" or "")
    end