//! Raw vector: type-unsafe dynamic array backed by static storage.

//!

//! Users provide their own arena (static array) and the vector manages

//! element count within that arena. The arena should be aligned according

//! to the element type's requirements.

/// Raw vector metadata structure.

///

/// Does not own storage, points to user-provided arena.

export record RawVec {

    /// Pointer to user-provided byte arena.

    data: *mut [u8],

    /// Current number of elements stored.

    len: u32,

    /// Size of each element in bytes (stride between elements).

    stride: u32,

    /// Alignment in bytes required by element type (>= 1).

    alignment: u32,

}

/// Create a new raw vector with external arena.

///

/// * `arena` is a pointer to static array backing storage.

/// * `stride` is the size of each element.

/// * `alignment` is the required alignment for elements.

export fn new(arena: *mut [u8], stride: u32, alignment: u32) -> RawVec {

    assert stride > 0;

    assert alignment > 0;

    assert (arena.ptr as u32) % alignment == 0;

    assert (arena.len % stride) == 0;

    return RawVec { data: arena, len: 0, stride, alignment };

}

/// Get the current number of elements in the vector.

export fn len(vec: *RawVec) -> u32 {

    return vec.len;

}

/// Get the maximum capacity of the vector.

export fn capacity(vec: *RawVec) -> u32 {

    return vec.data.len / vec.stride;

}

/// Reset the vector to empty (does not clear memory).

export fn reset(vec: *mut RawVec) {

    set vec.len = 0;

}

/// Get a pointer to the element at the given index.

///

/// Returns nil if index is out of bounds.

export fn get(vec: *RawVec, index: u32) -> ?*opaque {

    if index >= vec.len {

        return nil;

    }

    let offset: u32 = index * vec.stride;

    let ptr: *u8 = &vec.data[offset];

    return ptr as *opaque;

}

/// Push an element onto the end of the vector.

///

/// Returns false if the vector is at capacity.

///

/// The caller must preserve the metadata invariants established by [`new`],

/// including `vec.stride > 0` and `vec.len <= capacity(vec)`. When the vector

/// has spare capacity, `elem` must point to at least `vec.stride` readable,

/// initialized bytes, and the destination range beginning at

/// `vec.len * vec.stride` in `vec.data` must be writable for `vec.stride`

/// bytes. The copy is byte-wise, so `elem` has no alignment requirement and

/// the destination need not already be initialized.

export unsafe fn push(vec: *mut RawVec, elem: *opaque) -> bool {

    if vec.len >= capacity(vec) {

        return false;

    }

    let off: u32 = vec.len * vec.stride;

    let dst: *mut u8 = &mut vec.data[off];

    let src: *u8 = elem as *u8;

    copyBytes(dst, src, vec.stride);

    set vec.len += 1;

    return true;

}

/// Pop an element from the end of the vector.

///

/// Copies the element into the provided output pointer.

/// Returns false if the vector is empty.

///

/// The caller must preserve the metadata invariants established by [`new`],

/// including `vec.stride > 0` and `vec.len <= capacity(vec)`. When the vector

/// is non-empty, `out` must point to at least `vec.stride` writable bytes, and

/// the source range for the last logical element in `vec.data` must contain

/// `vec.stride` initialized bytes. The copy is byte-wise, so `out` has no

/// alignment requirement and its previous contents need not be initialized.

export unsafe fn pop(vec: *mut RawVec, out: *mut opaque) -> bool {

    if vec.len == 0 {

        return false;

    }

    set vec.len -= 1;

    let off: u32 = vec.len * vec.stride;

    let src: *u8 = &vec.data[off];

    let dst: *mut u8 = out as *mut u8;

    copyBytes(dst, src, vec.stride);

    return true;

}

/// Set the element at the given index.

///

/// Returns false if index is out of bounds.

///

/// The caller must preserve the metadata invariants established by [`new`],

/// including `vec.stride > 0` and `vec.len <= capacity(vec)`. When `index` is

/// in bounds, `elem` must point to at least `vec.stride` readable, initialized

/// bytes, and the destination range beginning at `index * vec.stride` in

/// `vec.data` must be writable for `vec.stride` bytes. The copy is byte-wise,

/// so `elem` has no alignment requirement.

export unsafe fn put(vec: *mut RawVec, index: u32, elem: *opaque) -> bool {

    if index >= vec.len {

        return false;

    }

    let off: u32 = index * vec.stride;

    let dst: *mut u8 = &mut vec.data[off];

    let src: *u8 = elem as *u8;

    copyBytes(dst, src, vec.stride);

    return true;

}

/// Copy `count` initialized bytes from `src` into writable storage at `dst`.

///

/// The caller must ensure both pointers are valid for `count` bytes. No

/// alignment is required because the copy operates one byte at a time.

unsafe fn copyBytes(dst: *mut u8, src: *u8, count: u32) {

    for i in 0..count {

        set *(dst + i) = *(src + i);

    }

}