ptr.or

// Pointer operations module
//
// Provides safe wrappers around low-level pointer operations.
// All functions in this module are unsafe and must be called within
// unsafe blocks or unsafe functions.

/// Get the address of a value
///
/// Creates a pointer to the given value by allocating it on the stack.
///
/// # Safety
/// - The returned pointer is only valid while the value is alive
/// - Do not dereference after the value goes out of scope
///
/// # Examples
/// ```
/// unsafe {
///     let x = 42
///     let ptr = std.ptr.addr_of(x)
///     let y = std.ptr.read(ptr)
///     // y == 42
/// }
/// ```
pub unsafe fn addr_of(value: a) -> Ptr[a] {
    @ptr_of(value)
}

/// Read a value from a pointer
///
/// Loads the value at the memory location pointed to by the pointer.
///
/// # Safety
/// - Pointer must be valid (not null, properly aligned)
/// - Pointed-to value must be initialized
/// - Must not violate aliasing rules
///
/// # Examples
/// ```
/// unsafe {
///     let x = 42
///     let ptr = std.ptr.addr_of(x)
///     let y = std.ptr.read(ptr)
///     // y == 42
/// }
/// ```
pub unsafe fn read(ptr: Ptr[a]) -> a {
    @ptr_read(ptr)
}

/// Write a value to a pointer
///
/// Stores the given value at the memory location pointed to by the pointer.
///
/// # Safety
/// - Pointer must be valid (not null, properly aligned)
/// - Must not violate aliasing rules
/// - Overwrites existing value without dropping
///
/// # Examples
/// ```
/// unsafe {
///     let x = 10
///     let ptr = std.ptr.addr_of(x)
///     std.ptr.write(ptr, 42)
///     let y = std.ptr.read(ptr)
///     // y == 42
/// }
/// ```
pub unsafe fn write(ptr: Ptr[a], value: a) -> Unit {
    @ptr_write(ptr, value)
}

/// Offset a pointer by a number of elements
///
/// Performs pointer arithmetic to get a pointer to the element at
/// the given offset from the base pointer.
///
/// # Safety
/// - Must not overflow pointer arithmetic
/// - Resulting pointer must be in bounds or one past the end of allocation
/// - Original pointer must point to an array or allocated region
///
/// # Examples
/// ```
/// unsafe {
///     // Assuming array is at ptr
///     let second = std.ptr.offset(ptr, 1)
///     let value = std.ptr.read(second)
/// }
/// ```
pub unsafe fn offset(ptr: Ptr[a], count: I64) -> Ptr[a] {
    @ptr_offset(ptr, count)
}

/// Swap values at two pointers
///
/// Exchanges the values at two memory locations.
///
/// # Safety
/// - Both pointers must be valid
/// - Pointers must not alias (point to same location)
/// - Both locations must contain valid, initialized values
///
/// # Examples
/// ```
/// unsafe {
///     let x = 10
///     let y = 20
///     let px = std.ptr.addr_of(x)
///     let py = std.ptr.addr_of(y)
///     std.ptr.swap(px, py)
///     // x == 20, y == 10
/// }
/// ```
pub unsafe fn swap(a: Ptr[t], b: Ptr[t]) -> Unit {
    unsafe {
        let tmp = read(a)
        let b_val = read(b)
        write(a, b_val)
        write(b, tmp)
    }
}