Module

std::ptr

Pointer Module

Thin wrapper for raw pointers with small utility methods.

Overview

Pointer<T> does not add ownership or safety guarantees. It only groups common pointer operations into a single record API.

What This Type Is

Pointer<T> is a convenience wrapper around *mut T that provides:

  • Null checks
  • Address conversion helpers
  • Pointer arithmetic helpers
  • Read/write helpers for direct memory access

It is useful when low-level code wants method-call style APIs while still operating on raw pointers.

What This Type Is Not

It is not a smart pointer and does not:

  • Manage memory lifetime
  • Prevent aliasing bugs
  • Validate bounds
  • Guarantee alignment

Safety

The caller is responsible for ensuring all pointer operations are valid. Dereferencing a null, dangling, unaligned, or out-of-bounds pointer is undefined behavior.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";
import String from "std::string";
import Io from "std::io";

function main(): i32 {
  let raw: *mut i32 = Memory::allocateVector<i32>(2);
  let mut ptr: Pointer<i32> = Pointer::init(raw);

  ptr.write(10);
  ptr.writeAt(1, 20);

  Io::println(String::toString(ptr.read()));
  Io::println(String::toString(ptr.readAt(1)));

  Memory::free(raw);
  return 0;
}

Records

record Pointer<T>

Method-style wrapper around a raw pointer.

Method Reference

Method Signature Description
init () -> Pointer<T> Null pointer
init (*mut T) -> Pointer<T> From mutable raw pointer
fromConst (*T) -> Pointer<T> From const raw pointer
isNull (&self) -> boolean Null check
asPtr (&self) -> *T Immutable raw pointer
asMutPtr (&self) -> *mut T Mutable raw pointer
toAddress (&self) -> u64 Address as integer
set (&mut self, *mut T) -> void Replace wrapped pointer
offset (&self, i64) -> Pointer<T> Signed element offset
add (&self, u64) -> Pointer<T> Forward by elements
sub (&self, u64) -> Pointer<T> Backward by elements
distance (&self, Pointer<T>) -> i64 Element distance between two
read (&self) -> T Dereference
write (&mut self, T) -> void Write through pointer
readAt (&self, i64) -> T Indexed read
writeAt (&mut self, i64, T) -> void Indexed write
equals (&self, Pointer<T>) -> boolean Address equality

Pointer Arithmetic

Offsets are in elements, not bytes. The underlying arithmetic scales by @sizeOf<T>() automatically:

  base           base + 1       base + 2       base + 3
  |              |              |              |
  v              v              v              v
  +--------------+--------------+--------------+---
  | element 0    | element 1    | element 2    | ...
  +--------------+--------------+--------------+---
  |<- sizeOf<T> ->|

Example

import Pointer from "std::ptr";

let mut x: i32 = 10;
let p: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
Members
address: *mut T

Wrapped raw pointer.

static fromConst(address: *T): Pointer<T>

Creates a pointer from a const raw pointer.

Example

import Pointer from "std::ptr";

let x: i32 = 10;
let p: Pointer<i32> = Pointer::fromConst((&x) as *i32);
static init(address: *mut T): Pointer<T>
static init(address: *mut T): Pointer<T>
static new(): Pointer<T>

Creates a null pointer.

Example

import Pointer from "std::ptr";

let p: Pointer<i32> = Pointer::new<i32>();
add(&self, count: u64): Pointer<T>

Returns a new pointer moved forward by count elements.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";

let raw: *mut i32 = Memory::allocateVector<i32>(2);
let p0: Pointer<i32> = Pointer::init(raw);
let p1: Pointer<i32> = p0.add(1);
Memory::free(raw);
asMutPtr(&self): *mut T

Returns this pointer as mutable raw pointer.

Example

import Pointer from "std::ptr";

let mut x: i32 = 10;
let p: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
let raw: *mut i32 = p.asMutPtr();
asPtr(&self): *T

Returns this pointer as immutable raw pointer.

Example

import Pointer from "std::ptr";

let mut x: i32 = 10;
let p: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
let raw: *i32 = p.asPtr();
distance(&self, other: Pointer<T>): i64

Returns the distance to another pointer in elements.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";

let raw: *mut i32 = Memory::allocateVector<i32>(4);
let a: Pointer<i32> = Pointer::init(raw);
let b: Pointer<i32> = a.add(3);
let d: i64 = b.distance(a);
Memory::free(raw);
equals(&self, other: Pointer<T>): boolean

Checks whether two pointers refer to the same address.

Example

import Pointer from "std::ptr";

let mut x: i32 = 10;
let a: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
let b: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
let same: boolean = a.equals(b);
isNull(&self): boolean

Returns whether this pointer is null.

Example

import Pointer from "std::ptr";

let p: Pointer<i32> = Pointer::new<i32>();
let isNull: boolean = p.isNull();
offset(&self, count: i64): Pointer<T>

Returns a new pointer offset by count elements.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";

let raw: *mut i32 = Memory::allocateVector<i32>(2);
let p0: Pointer<i32> = Pointer::init(raw);
let p1: Pointer<i32> = p0.offset(1);
Memory::free(raw);
read(&self): T

Reads the value pointed to by this pointer.

Example

import Pointer from "std::ptr";

let mut x: i32 = 10;
let p: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
let value: i32 = p.read();
readAt(&self, index: i64): T

Reads the value at index elements from this pointer.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";

let raw: *mut i32 = Memory::allocateVector<i32>(2);
let mut p: Pointer<i32> = Pointer::init(raw);
p.writeAt(0, 10);
p.writeAt(1, 20);
let value: i32 = p.readAt(1);
Memory::free(raw);
set(&mut self, address: *mut T): void

Replaces the wrapped raw pointer.

Example

import Pointer from "std::ptr";

let mut a: i32 = 1;
let mut b: i32 = 2;
let mut p: Pointer<i32> = Pointer::init((&mut a) as *mut i32);
p.set((&mut b) as *mut i32);
sub(&self, count: u64): Pointer<T>

Returns a new pointer moved backward by count elements.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";

let raw: *mut i32 = Memory::allocateVector<i32>(2);
let p1: Pointer<i32> = Pointer::init(raw).add(1);
let p0: Pointer<i32> = p1.sub(1);
Memory::free(raw);
toAddress(&self): u64

Returns the pointer address as an integer.

Example

import Pointer from "std::ptr";

let mut x: i32 = 10;
let p: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
let address: u64 = p.toAddress();
write(&mut self, value: T): void

Writes a value through this pointer.

Example

import Pointer from "std::ptr";

let mut x: i32 = 0;
let mut p: Pointer<i32> = Pointer::init((&mut x) as *mut i32);
p.write(42);
writeAt(&mut self, index: i64, value: T): void

Writes value at index elements from this pointer.

Example

import Pointer from "std::ptr";
import Memory from "std::memory";

let raw: *mut i32 = Memory::allocateVector<i32>(2);
let mut p: Pointer<i32> = Pointer::init(raw);
p.writeAt(0, 10);
p.writeAt(1, 20);
Memory::free(raw);