module.ae

// std.list - ArrayList Operations (alias for std.collections)
//
// API shape:
//   - Raw externs end in `_raw` and return ptr/int in the old C-style
//     convention. They are the escape hatch for advanced callers.
//   - Aether-native wrappers (below) use Go-style `(value, err)` / `err`
//     returns.

exports(
    list_new, list_new_in, list_add_raw, list_add_string_owned, list_get_raw, list_set, list_size,
    list_remove, list_clear, list_free,
    add, get
)

extern list_new() -> ptr
extern list_new_in(alloc: ptr) -> ptr
extern list_add_raw(list: ptr, item: ptr) -> int
// Heap-string-aware add. The list acquires its OWN reference: a
// refcounted string is retained, a plain pointer (a literal, a
// borrowed char*) is copied. The caller keeps and independently frees
// theirs, so the same value can live in several containers. list_free
// releases each owned element before freeing the backing array.
// Codegen auto-routes `list.add(l, heap_string_expr)` to the adopting
// sibling instead, where the value is escaping into the list and the
// caller does not release it.
extern list_add_string_owned(list: ptr, item: ptr) -> int
extern list_get_raw(list: ptr, index: int) -> ptr
extern list_set(list: ptr, index: int, item: ptr)
extern list_size(list: ptr) -> int
extern list_remove(list: ptr, index: int)
extern list_clear(list: ptr)
extern list_free(list: ptr)

// Append an item to a list. Returns "" on success, error on failure.
add(list: ptr, item: ptr) -> {
    ok = list_add_raw(list, item)
    if ok == 0 {
        return "list.add failed"
    }
    return ""
}

// Index into a list.
// - (item, "")           : index in range
// - (null, "")           : index out of range (not an error)
// - (null, "null list")  : `list` is null
get(list: ptr, index: int) -> {
    if list == null {
        return null, "null list"
    }
    item = list_get_raw(list, index)
    return item, ""
}