stringx Module

Public Luau surface over the __stringx Internal FFI namespace — batch text-scanning kernels.

Purpose

Read a whole run of numbers out of a string in one call, for the cases where a Luau parser's cost is its token count rather than its byte count.

Locating one token with a Luau pattern is a crossing into the pattern matcher, and that crossing costs roughly 1.3µs however little work follows it. Measured on a clip's animation JSON — 336KB holding 16,057 numbers:

	ms
full json.decode	32.7
find + sub + tonumber, no structure	21.6
gmatch alone — only locating the tokens	22.6

Finding the numbers is 66% of the decode, and finding them costs the same as finding and converting them: the string.sub and the tonumber are nearly free next to the match. So the wall is the per-token crossing, and the fix is to cross once for the whole run.

Not a format

A JSON array, a CSV row, an OBJ vertex block, a glTF accessor and a matrix dump are the same shape — a run of numbers with separators. This reads that shape and nothing else. Structure stays in Luau: keep your own parser and reach for this only at the point where the token count is what hurts.

Usage

-- Inside a parser, at a '[' whose first element is numeric:
local values, nextPos = stringx.scanNumbers(payload, pos)
-- `nextPos` is the first character that is neither a number nor a separator,
-- so the surrounding parser resumes there.

-- A whitespace-separated block:
local m = stringx.scanNumbers("1 0 0 0  0 1 0 0  0 0 1 0  0 0 0 1", 1)

Exports

• scanNumbers(s, pos?) → { number }, nextPos

Single-number forms are out of scope, the same way mathx has no single-value ops: tonumber already does that at sub-µs cost and the FFI overhead would dominate.