package core:container/xar

Source

Iterator state for traversing a Xar.

Fields: xar: Pointer to the exponential array being iterated idx: Current iteration index

• iterate_by_ptr
• iterate_by_val

• iterator

An Exponential Array with stable element addresses.

Unlike [dynamic]T which reallocates and moves elements when growing, Xar allocates separate chunks of exponentially increasing size. This guarantees that pointers to elements remain valid for the lifetime of the container.

Fields: chunks: Fixed array of multi-pointers to allocated chunks len: Number of elements currently stored allocator: Allocator used for chunk allocations

Type Parameters: T: The element type SHIFT: Controls initial chunk size (1 << SHIFT). Must be in range (0, MAX_SHIFT]. Larger values mean fewer, bigger chunks. Recommended: 4-8.

Chunk sizes grow as: chunks[0]: 1 << SHIFT elements chunks[1]: 1 << SHIFT elements chunks[2]: 1 << (SHIFT + 1) elements chunks[3]: 1 << (SHIFT + 2) elements chunks[4]: 1 << (SHIFT + 3) elements ...and so on

import "core:container/xar"

example :: proc() {
	// Xar with initial chunk size of 16 (1 << 4)
	x: xar.Xar(My_Struct, 4)
	defer xar.destroy(&x)
}

• cap
• clear
• destroy
• get
• get_ptr
• init
• iterator
• len
• pop
• pop_safe
• push_back_elem
• push_back_elem_and_get_ptr
• push_back_elems
• set
• unordered_remove
• append (procedure groups)
• push_back (procedure groups)

Append an element and return a stable pointer to it. This is useful when you need to initialize a complex struct in-place or retain a reference to the newly added element.

Inputs x: Pointer to the exponential array value: The element to append

Returns a stable pointer to the newly added element allocation error if chunk allocation failed

import "core:container/xar"

push_back_and_get_ptr_example :: proc() {
	x: xar.Xar(My_Struct, 4)
	defer xar.destroy(&x)

	ptr := xar.push_back_elem_and_get_ptr(&x, My_Struct{}) or_else panic("alloc failed")
	ptr.field = 42  // Initialize in-place
}

Returns the number of allocated elements

Resets the array's length to zero without freeing memory. Allocated chunks are retained for reuse.

Frees all allocated chunks and resets the exponential array.

Inputs x: Pointer to the exponential array to destroy

Get a copy of the element at the specified index.

Inputs x: Pointer to the exponential array index: Position of the element (0-indexed)

Returns a copy of the element

Get a pointer to the element at the specified index.

The returned pointer remains valid even after additional elements are added, as long as the element is not removed and the array is not destroyed.

Inputs x: Pointer to the exponential array index: Position of the element (0-indexed)

Returns a stable pointer to the element

import "core:container/xar"

get_ptr_example :: proc() {
	x: xar.Xar(int, 4)
	defer xar.destroy(&x)

	xar.push_back(&x, 100)
	ptr := xar.get_ptr(&x, 0)

	// Pointer remains valid after growing
	for i in 0..<1000 {
		xar.push_back(&x, i)
	}

	fmt.println(ptr^)  // Still prints 100
}

Initializes an exponential array with the given allocator.

Inputs x: Pointer to the exponential array to initialize allocator: Allocator to use for chunk allocations (defaults to context.allocator)

Advance the iterator and returns a pointer to the next element.

Inputs it: Pointer to the iterator

Returns pointer to the current element true if an element was returned, false if iteration is complete

Advance the iterator and returns the next element.

Inputs it: Pointer to the iterator

Returns current element true if an element was returned, false if iteration is complete

Create an iterator for traversing the exponential array.

Inputs xar: Pointer to the exponential array

Returns an iterator positioned at the start

import "lib:xar"

iteration_example :: proc() {
	x: xar.Xar(int, 4)
	defer xar.destroy(&x)

	xar.push_back(&x, 10)
	xar.push_back(&x, 20)
	xar.push_back(&x, 30)

	it := xar.iterator(&x)
	for val in xar.iterate_by_ptr(&it) {
		fmt.println(val^)
	}
}

10
20
30

Returns the length of the exponential-array

pop will remove and return the end value of an exponential array x and reduces the length of the array by 1.

Note: If the exponential array has no elements (xar.len(x) == 0), this procedure will panic.

pop_safe trys to remove and return the end value of dynamic array x and reduces the length of the array by 1. If the operation is not possible, it will return false.

Append an element to the end of the exponential array. Allocates a new chunk if necessary. Existing elements aren't moved, and their pointers remain stable.

Inputs x: Pointer to the exponential array value: The element to append

Returns number of elements added (always 1 on success) allocation error if chunk allocation failed

import "core:container/xar"

push_back_example :: proc() {
	x: xar.Xar(string, 4)
	defer xar.destroy(&x)

	xar.push_back(&x, "hello")
	xar.push_back(&x, "world")

	fmt.println(xar.get(&x, 0))  // hello
	fmt.println(xar.get(&x, 1))  // world
}

• append
• push_back

Append an element and return a stable pointer to it. This is useful when you need to initialize a complex struct in-place or retain a reference to the newly added element.

Inputs x: Pointer to the exponential array value: The element to append

Returns a stable pointer to the newly added element allocation error if chunk allocation failed

import "core:container/xar"

push_back_and_get_ptr_example :: proc() {
	x: xar.Xar(My_Struct, 4)
	defer xar.destroy(&x)

	ptr := xar.push_back_elem_and_get_ptr(&x, My_Struct{}) or_else panic("alloc failed")
	ptr.field = 42  // Initialize in-place
}

Append multiple elements to the end of the exponential array.

Inputs x: Pointer to the exponential array values: The elements to append

Returns number of elements successfully added allocation error if chunk allocation failed (partial append possible)

• append
• push_back

Set the element at the specified index to the given value.

Inputs x: Pointer to the exponential array index: Position of the element (0-indexed) value: The value to set

unordered_remove removed the element at the specified index. It does so by replacing the current end value with the old value, and reducing the length of the exponential array by 1.

Note: This is an O(1) operation. Note: This is currently no procedure that is the equivalent of an "ordered_remove" Note: If the index is out of bounds, this procedure will panic.

Note: Pointers to the last element become invalid (it gets moved). Pointers to other elements remain valid.

import "core:encoding/xar"

unordered_remove_example :: proc() {
	x: xar.Xar(int, 4)
	defer xar.destroy(&x)

	xar.push_back(&x, 10)
	xar.push_back(&x, 20)
	xar.push_back(&x, 30)

	xar.unordered_remove(&x, 0)  // Removes 10, replaces with 30

	// Array now contains [30, 20]
	fmt.println(xar.get(&x, 0))  // 30
	fmt.println(xar.get(&x, 1))  // 20
}