utils

String / encoding / hashing / time / persistence utilities. Domain-agnostic — does not overlap with file / input / json etc.

---

Encoding

utils.base64_encode(text) → string

Standard RFC 4648 base64 with = padding. Input is treated as a byte stream (may contain \0 etc).

utils.base64_decode(text) → string

Decodes base64. \n / \r / space are skipped; invalid characters are tolerated (no error). = padding handled.

utils.array_to_string(bytes) → string

1-based byte table → string (elements 0–255). Useful for hand-rolling binary protocols; file.read already returns a string and does not need this.

utils.string_to_array(text) → table<int>

String → 1-based byte table.

---

Hashing

utils.murmur2(text) → int

MurmurHash2 32-bit (Austin Appleby original, seed=0). Returns a uint32 (LuaJIT integer-safe up to 2^53).

utils.fnv1a(text) → int

FNV-1a 32-bit.

---

Time

utils.unix_time() → int

Current Unix timestamp (seconds). Different from time.now() — time.now() is a monotonic steady_clock, not a wall clock. Use unix_time() for log timestamps or server sync.

utils.get_date() → table

Current local date/time as {year, month, day, hour, minute, second, dst}.

---

Clipboard

Clipboard has moved out of utils.*. Use input.clipboard_get / input.clipboard_set.

---

Script-scoped KV persistence

db_save / db_load store data scoped to the calling script (as opposed to config.* which is global). Files land in conf/lua_db/<owner-hash>__<key>.json; owner is automatically the current _SCRIPT_PATH, so the same key in different scripts does not collide.

Values pass through json.encode/decode, so any combination of table / string / number / bool / nil works (functions and userdata do not).

utils.db_save(key, value) → bool

• key: [a-zA-Z0-9_.-]+ and ≤64 chars; invalid keys return false.
• Returns true on success; failures are logged.

utils.db_load(key, default?) → value

• Same key rules as above.
• Missing key or parse failure returns default (default nil).

---

Example

-- HTTP Basic Auth
local cred = utils.base64_encode("user:pass")
net.http:get("https://api.example.com/private", {
    headers = { ["Authorization"] = "Basic " .. cred }
}, function(r) end)

-- Hash a config id to dedupe
local id = utils.fnv1a(json.encode(cfg))

-- Log with timestamp
log.info(("[%d] %s"):format(utils.unix_time(), msg))

-- Run once per day
local d = utils.get_date()
local today = ("%04d-%02d-%02d"):format(d.year, d.month, d.day)
if utils.db_load("last_day") ~= today then
    log.info("new day: " .. today)
    utils.db_save("last_day", today)
end

-- Persist UI state across sessions
local saved = utils.db_load("ui_pos", { x = 100, y = 100 })
event.on("frame_update", function()
    -- ... on drag end:
    utils.db_save("ui_pos", { x = win.x, y = win.y })
end)