Relative_Pointers

Available on macOS, Linux, Windows, Wasm

#import "Relative_Pointers";

Pointers stored as a small offset from their own address, so a block of memory that holds them can be written to a file or moved and still make sense.

Relative_Pointer holds one pointer; encode sets it and decode reads it.
Relative_String holds a string the same way.
write_relative_pointer and decode_relative_pointer work on raw storage.

Example↗

Node :: struct {
    next: Relative_Pointer(s16, u8);
    value: u8;
}

nodes: [2] Node;
nodes[1].value = 9;
encode(*nodes[0].next, *nodes[1].value);
assert(decode(*nodes[0].next).* == 9);

Procedures#

decode2 overloadsSource

(p: *Relative_Pointer) -> result: *p.Pointer_To_Type

(p: *Relative_String) -> string

Returns the pointer a Relative_Pointer holds, or null if it is unset.

target: u8 = 5;
holder: struct { pointer: Relative_Pointer(s32, u8); };
encode(*holder.pointer, *target);
assert(decode(*holder.pointer) == *target);

↗

encodeSource

(p: *Relative_Pointer, absolute: *p.Pointer_To_Type)

Points p at absolute, or clears it when absolute is null. The target must be within range of what Storage_Type can reach.

decode_relative_pointer2 overloadsSource

(relative_pointer_size: s32, address: *void) -> (pointer: *void, offset: s64)

(relative_pointer_size: s32, pointer_address: *void, base_address: *void) -> (pointer: *void, offset: s64)

Reads the relative pointer of relative_pointer_size bytes (1, 2, 4 or 8) at address. Returns the pointer, or null if it is unset, and its offset from address.

decode_relative_pointer_staticSource

($type: Type, address: *void) -> pointer: *void

Reads the relative pointer at address, taking its size from the integer type type.

write_relative_pointer2 overloadsSource

($type: Type, pointer_address: *void, target_address: *void)

($type: Type, pointer_address: *void, base_address: *void, target_address: *void)

Stores a relative pointer of integer type type at pointer_address that leads to target_address; null clears it.

slot: s16;
value: u8;
write_relative_pointer(s16, *slot, *value);
assert(decode_relative_pointer_static(s16, *slot) == *value);

↗

Types#

Relative_PointerstructSource

:: struct

A pointer to a Pointer_To_Type, stored as a signed Storage_Type (s8 to s64) offset from its own address. An offset of zero means null, so a pointer to its own address cannot be stored.

value: Storage_Type

Relative_StringstructSource

:: struct

A string stored as a length and a relative pointer to its bytes, each a Storage_Type.

count: Storage_Type
data: Storage_Type