API Tiers

The API is split into two tiers. Pick the tier per call site.

Safe tier

Get, Set, PushBack, RemoveIndex, Iterate, Transform.

These maintain Count/Length, skip holes, and are safe to reach for by default.

Raw tier

GetChunk, SetChunk, IterateChunks, GetChunkAndPosition, and the exported InfArray.locate. These are the fastest path for bulk work, but you are responsible for nil-checking and respecting per-chunk lengths.

-- Safe: pays a callback + hole-skip per element
arr:Iterate(function(index, value) end)

-- Raw: fastest bulk throughput; you nil-check chunk[j] yourself
arr:IterateChunks(function(chunk, base, len)
    for j = 1, len do
        local v = chunk[j]
        if v ~= nil then
            -- global index is base + j
        end
    end
end)

Reach for the raw tier only in the inner loops where per-element overhead actually shows up in a profile. For measured numbers, see the Benchmarks tab.