module.ae

// std.floatarr - Fixed-size packed-double buffer (float twin of std.intarr)
//
// For SVG path-command args, rasterizer edge tables, bbox accumulators,
// blur kernel coefficients, and other hot paths where std.list's
// void*-boxed items cost an allocation per entry. Size is fixed at
// allocation — callers that need growth use std.list instead.
// Aether's `float` is a 64-bit C double, so the buffer is packed
// doubles end-to-end (not f32).
//
// API shape mirrors std.intarr exactly:
//   - Raw externs bounds-check on read (return 0.0 on OOB) and write
//     (no-op on OOB). Fast path uses the `_unchecked` variants.
//   - Go-style wrappers (`new`, `get`, `set`) return tuples/errors
//     for callers that want to distinguish "absent" from "stored zero".

exports(
    new, new_filled, get, set,
    floatarr_new_raw, floatarr_new_filled_raw,
    floatarr_size, floatarr_get_raw, floatarr_set_raw,
    floatarr_get_unchecked, floatarr_set_unchecked,
    floatarr_fill, floatarr_free
)

// ---- Raw externs (escape hatch; also the hot-path API) ----

// Allocate a FloatArray of `size` doubles, zero-initialised. Returns
// null if `size` is negative or allocation fails.
extern floatarr_new_raw(size: int) -> ptr

// Allocate and fill every index with `init`.
extern floatarr_new_filled_raw(size: int, init: float) -> ptr

// Number of elements. -1 if `arr` is null.
extern floatarr_size(arr: ptr) -> int

// Read at `i`. Returns 0.0 if `arr` is null or `i` is out-of-range.
// Use `floatarr.get` (below) to distinguish stored-zero from OOB.
extern floatarr_get_raw(arr: ptr, i: int) -> float

// Write `value` at `i`. No-op if `arr` is null or `i` is out-of-range.
// Use `floatarr.set` (below) if you need an error on OOB.
extern floatarr_set_raw(arr: ptr, i: int, value: float)

// Hot-path variants — caller guarantees index is in [0, size). OOB
// access is undefined behaviour. Don't use from outside a tight loop.
extern floatarr_get_unchecked(arr: ptr, i: int) -> float
extern floatarr_set_unchecked(arr: ptr, i: int, value: float)

// Fill every element with `value`.
extern floatarr_fill(arr: ptr, value: float)

// Release. Idempotent on null.
extern floatarr_free(arr: ptr)

// ---- Go-style wrappers ----

// Allocate a FloatArray of `size` elements, zero-initialised.
// Returns (ptr, "") on success, (null, error) on failure.
new(size: int) -> {
    if size < 0 {
        return null, "negative size"
    }
    a = floatarr_new_raw(size)
    if a == null {
        return null, "allocation failed"
    }
    return a, ""
}

// Allocate and fill with `init` at every index.
new_filled(size: int, init: float) -> {
    if size < 0 {
        return null, "negative size"
    }
    a = floatarr_new_filled_raw(size, init)
    if a == null {
        return null, "allocation failed"
    }
    return a, ""
}

// Bounds-checked read. Returns (value, "") on success, (0.0, error)
// for null array or OOB index. Use the raw `floatarr_get_raw`
// directly (imported above) when you don't need to tell absent apart
// from stored-zero — it's one fewer function call and one fewer branch.
get(arr: ptr, i: int) -> {
    if arr == null {
        return 0.0, "null array"
    }
    n = floatarr_size(arr)
    if i < 0 {
        return 0.0, "index out of range"
    }
    if i >= n {
        return 0.0, "index out of range"
    }
    return floatarr_get_raw(arr, i), ""
}

// Bounds-checked write. Returns "" on success, error for null array
// or OOB index. Use the raw `floatarr_set_raw` directly in hot paths
// where a no-op-on-OOB is acceptable.
set(arr: ptr, i: int, value: float) -> {
    if arr == null {
        return "null array"
    }
    n = floatarr_size(arr)
    if i < 0 {
        return "index out of range"
    }
    if i >= n {
        return "index out of range"
    }
    floatarr_set_raw(arr, i, value)
    return ""
}