# utils 套件

本頁列出 `core/utils` 的公開輔助函式，負責指令文字與已解碼 JSON 值之間的轉換，以及走訪巢狀路徑。

## 函式

```go
import "github.com/pardnchiu/toriidb/core/utils"

func WalkKeys(obj any, subKeys []string) (any, bool)
func Atov(text string) any
func Vtoa(value any) string
func Vtof(value any) (float64, bool)
```

| 函式 | 行為 | 使用處 |
|---|---|---|
| `utils.WalkKeys` | 沿 `subKeys` 走訪已解碼的 JSON：`map[string]any` 依欄位名、`[]any` 依十進位索引。欄位不存在、索引非數字／為負／超出範圍，或路徑中途遇到純量時回傳 `false`。`subKeys` 為空時回傳 `obj` 本身 | `GetField`、`IncrField`、`filter.Cond` |
| `utils.Atov` | 把指令文字轉成 JSON 值：`null` → `nil`、`true`/`false` → `bool`、整數 → `int64`、其他數字 → `float64`、去除空白後可解析的 `{...}`/`[...]` → object 或 array，其餘 → `string` | `SetField` |
| `utils.Vtoa` | 把已解碼的值轉成文字：`nil` → `(nil)`、整數值的 `float64` 不帶小數點、其他 `float64` 取最短表示、`bool` 為 `true`/`false`、object 與 array 為精簡 JSON，其他型別以 `%v` 輸出 | `GetField`、`Incr`、`Exec`、`filter.Cond` |
| `utils.Vtof` | 輸入為 `float64` 或 `int64` 時以 `float64` 回傳；其他型別（含數字字串）回傳 `false` | `IncrField` |

## 往返規則

- `QUERY` 中 `1.0` 與 `1` 會相等，是因為 `Vtoa` 都把它們輸出為 `1`。
- `Atov` 把整數保留為 `int64`，但從已存 JSON 解碼出的數值是 `float64`；`Vtof` 兩者都接受，所以對 JSON 欄位 `INCR` 兩種情況都可運作。
- 看起來像 JSON 但解析失敗的值會維持字串。

## 相關頁面

- [寫入 JSON 欄位](/zh/json-documents-writes)
- [QUERY 運算式](/zh/querying-query)
- [filter](/zh/api-reference-filter)