package core:container/small_array
Overview
Package small_array implements a dynamic array like interface on a stack-allocated, fixed-size array.
The Small_Array type is optimal for scenarios where you need a container for a fixed number of elements of a specific type, with the total number known at compile time but the exact number to be used determined at runtime.
Example:
import "core:fmt"
import "core:container/small_array"
create :: proc() -> (result: small_array.Small_Array(10, rune)) {
// appending single elements
small_array.push(&result, 'e')
// pushing a bunch of elements at once
small_array.push(&result, 'l', 'i', 'x', '-', 'e')
// pre-pending
small_array.push_front(&result, 'H')
// removing elements
small_array.ordered_remove(&result, 4)
// resizing to the desired length (the capacity will stay unchanged)
small_array.resize(&result, 7)
// inserting elements
small_array.inject_at(&result, 'p', 5)
// updating elements
small_array.set(&result, 3, 'l')
// getting pointers to elements
o := small_array.get_ptr(&result, 4)
o^ = 'o'
// and much more ....
return
}
// the Small_Array can be an ordinary parameter 'generic' over
// the actual length to be usable with different sizes
print_elements :: proc(arr: ^small_array.Small_Array($N, rune)) {
for r in small_array.slice(arr) {
fmt.print(r)
}
}
main :: proc() {
arr := create()
// ...
print_elements(&arr)
}
Hellope
Index
Types (1)
Constants (0)
This section is empty.
Variables (0)
This section is empty.
Types
Small_Array ¶
Small_Array :: struct($N: int, $T: typeid) where N >= 0 { … // See source for fields }
A fixed-size stack-allocated array operated on in a dynamic fashion.
Fields:
data: The underlying array
len: Amount of items that the Small_Array currently holds
Example:
import "core:container/small_array"
example :: proc() {
a: small_array.Small_Array(100, int)
small_array.push_back(&a, 10)
}
Related Procedures With Parameters
- clear
- consume
- get
- get_ptr
- get_ptr_safe
- get_safe
- inject_at
- ordered_remove
- pop_back
- pop_back_safe
- pop_front
- pop_front_safe
- push_back
- push_back_elems
- push_front
- set
- slice
- unordered_remove
- append (procedure groups)
- push (procedure groups)
Constants
This section is empty.
Variables
This section is empty.
Procedures
append_elem ¶
append_elem :: push_back
Attempts to add the given element to the end.
Inputs
a: A pointer to the small-array
item: The item to append
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
push_back_example :: proc() {
a: small_array.Small_Array(2, int)
assert(small_array.push_back(&a, 1), "this should fit")
assert(small_array.push_back(&a, 2), "this should fit")
assert(!small_array.push_back(&a, 3), "this should not fit")
fmt.println(small_array.slice(&a))
}
[1, 2]
append_elems ¶
append_elems :: push_back_elems
Attempts to append all elements to the small-array returning false if there is not enough space to fit all of them.
Inputs
a: A pointer to the small-array
item: The item to append
..:
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
push_back_elems_example :: proc() {
a: small_array.Small_Array(100, int)
small_array.push_back_elems(&a, 0, 1, 2, 3, 4)
fmt.println(small_array.slice(&a))
}
[0, 1, 2, 3, 4]
cap ¶
cap :: proc "contextless" (a: $A/Small_Array) -> int {…}
Returns the capacity of the small-array.
Inputs
a: The small-array
Returns the capacity
clear ¶
clear :: proc "contextless" (a: ^$A/Small_Array($N, $T)) {…}
Sets the length of the small-array to 0.
Inputs
a: A pointer to the small-array
Example:
import "core:container/small_array"
import "core:fmt"
clear_example :: proc() {
a: small_array.Small_Array(4, int)
small_array.push(&a, 0, 1, 2, 3)
fmt.println("BEFORE:", small_array.slice(&a))
small_array.clear(&a)
fmt.println("AFTER :", small_array.slice(&a))
}
BEFORE: [0, 1, 2, 3] AFTER : []
consume ¶
consume :: proc(a: ^$A/Small_Array($N, $T), count: int, loc := #caller_location) {…}
Decreases the length of the small-array by the given amount.
The elements are therefore not really removed and can be
recovered by calling resize.
Note: This procedure assumes that the array has a sufficient length.
Inputs
a: A pointer to the small-array
count: The amount the length should be reduced by
Example:
import "core:container/small_array"
import "core:fmt"
consume_example :: proc() {
a: small_array.Small_Array(3, int)
small_array.push(&a, 0, 1, 2)
fmt.println("BEFORE:", small_array.slice(&a))
small_array.consume(&a, 2)
fmt.println("AFTER :", small_array.slice(&a))
}
BEFORE: [0, 1, 2] AFTER : [0]
get ¶
get :: proc "contextless" (a: $A/Small_Array($N, $T), index: int) -> $T {…}
Get a copy of the item at the specified position. This operation assumes that the small-array is large enough.
This will result in:
- the value if 0 <= index < len - the zero value of the type if len < index < capacity - 'crash' if capacity < index or index < 0
Inputs
a: The small-array
index: The position of the item to get
Returns the element at the specified position
get_ptr ¶
get_ptr :: proc "contextless" (a: ^$A/Small_Array($N, $T), index: int) -> ^$T {…}
Get a pointer to the item at the specified position. This operation assumes that the small-array is large enough.
This will result in:
- the pointer if 0 <= index < len - the pointer to the zero value if len < index < capacity - 'crash' if capacity < index or index < 0
Inputs
a: A pointer to the small-array
index: The position of the item to get
Returns the pointer to the element at the specified position
get_ptr_safe ¶
get_ptr_safe :: proc(a: ^$A/Small_Array($N, $T), index: int) -> (^$T, bool) {…}
Get a pointer to the item at the specified position.
Inputs
a: A pointer to the small-array
index: The position of the item to get
Returns the pointer to the element at the specified position true if element exists, false otherwise
get_safe ¶
get_safe :: proc(a: $A/Small_Array($N, $T), index: int) -> ($T, bool) {…}
Attempt to get a copy of the item at the specified position.
Inputs
a: The small-array
index: The position of the item to get
Returns the element at the specified position true if element exists, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
get_safe_example :: proc() {
a: small_array.Small_Array(5, rune)
small_array.push_back(&a, 'A')
fmt.println(small_array.get_safe(a, 0) or_else 'x')
fmt.println(small_array.get_safe(a, 1) or_else 'x')
}
A x
inject_at ¶
inject_at :: proc "contextless" (a: ^$A/Small_Array($N, $T), item: $T, index: int) -> bool {…}
Tries to insert an element at the specified position.
Note: Performing this operation will cause pointers obtained through get_ptr(_save) to reference incorrect elements.
Inputs
a: A pointer to the small-array
item: The item to insert
index: The index to insert the item at
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
inject_at_example :: proc() {
arr: small_array.Small_Array(100, rune)
small_array.push(&arr, 'A', 'C', 'D')
small_array.inject_at(&arr, 'B', 1)
fmt.println(small_array.slice(&arr))
}
[A, B, C, D]
len ¶
len :: proc "contextless" (a: $A/Small_Array) -> int {…}
Returns the amount of items in the small-array.
Inputs
a: The small-array
Returns the amount of items in the array
ordered_remove ¶
ordered_remove :: proc "contextless" (a: ^$A/Small_Array($N, $T), index: int, loc := #caller_location) {…}
Removes the element at the specified index while retaining order.
Note: Performing this operation will cause pointers obtained through get_ptr(_save) to reference incorrect elements.
Inputs
a: A pointer to the small-array
index: The position of the element to remove
Example:
import "core:container/small_array"
import "core:fmt"
ordered_remove_example :: proc() {
a: small_array.Small_Array(4, int)
small_array.push(&a, 0, 1, 2, 3)
fmt.println("BEFORE:", small_array.slice(&a))
small_array.ordered_remove(&a, 1)
fmt.println("AFTER :", small_array.slice(&a))
}
BEFORE: [0, 1, 2, 3] AFTER : [0, 2, 3]
pop_back ¶
pop_back :: proc(a: ^$A/Small_Array($N, $T), loc := #caller_location) -> $T {…}
Removes and returns the last element of the small-array. This operation assumes that the small-array is not empty.
Inputs
a: A pointer to the small-array
Returns a copy of the element removed from the end of the small-array
Example:
import "core:container/small_array"
import "core:fmt"
pop_back_example :: proc() {
a: small_array.Small_Array(5, int)
small_array.push(&a, 0, 1, 2)
fmt.println("BEFORE:", small_array.slice(&a))
small_array.pop_back(&a)
fmt.println("AFTER: ", small_array.slice(&a))
}
BEFORE: [0, 1, 2] AFTER: [0, 1]
pop_back_safe ¶
pop_back_safe :: proc "contextless" (a: ^$A/Small_Array($N, $T)) -> (item: $T, ok: bool) {…}
Attempts to remove and return the last element of the small array.
Unlike pop_back, it does not assume that the array is non-empty.
Inputs
a: A pointer to the small-array
Returns a copy of the element removed from the end of the small-array true if the small-array was not empty, false otherwise
Example:
import "core:container/small_array"
pop_back_safe_example :: proc() {
a: small_array.Small_Array(3, int)
small_array.push(&a, 1)
el, ok := small_array.pop_back_safe(&a)
assert(ok, "there was an element in the array")
el, ok = small_array.pop_back_safe(&a)
assert(!ok, "there was NO element in the array")
}
pop_front ¶
pop_front :: proc(a: ^$A/Small_Array($N, $T), loc := #caller_location) -> $T {…}
Removes and returns the first element of the small-array. This operation assumes that the small-array is not empty.
Note: Performing this operation will cause pointers obtained through get_ptr(_save) to reference incorrect elements.
Inputs
a: A pointer to the small-array
Returns a copy of the element removed from the beginning of the small-array
Example:
import "core:container/small_array"
import "core:fmt"
pop_front_example :: proc() {
a: small_array.Small_Array(5, int)
small_array.push(&a, 0, 1, 2)
fmt.println("BEFORE:", small_array.slice(&a))
small_array.pop_front(&a)
fmt.println("AFTER: ", small_array.slice(&a))
}
BEFORE: [0, 1, 2] AFTER: [1, 2]
pop_front_safe ¶
pop_front_safe :: proc "contextless" (a: ^$A/Small_Array($N, $T)) -> (item: $T, ok: bool) {…}
Attempts to remove and return the first element of the small array.
Unlike pop_front, it does not assume that the array is non-empty.
Note: Performing this operation will cause pointers obtained through get_ptr(_save) to reference incorrect elements.
Inputs
a: A pointer to the small-array
Returns a copy of the element removed from the beginning of the small-array true if the small-array was not empty, false otherwise
Example:
import "core:container/small_array"
pop_front_safe_example :: proc() {
a: small_array.Small_Array(3, int)
small_array.push(&a, 1)
el, ok := small_array.pop_front_safe(&a)
assert(ok, "there was an element in the array")
el, ok = small_array.pop_front_(&a)
assert(!ok, "there was NO element in the array")
}
push_back ¶
push_back :: proc "contextless" (a: ^$A/Small_Array($N, $T), item: $T) -> bool {…}
Attempts to add the given element to the end.
Inputs
a: A pointer to the small-array
item: The item to append
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
push_back_example :: proc() {
a: small_array.Small_Array(2, int)
assert(small_array.push_back(&a, 1), "this should fit")
assert(small_array.push_back(&a, 2), "this should fit")
assert(!small_array.push_back(&a, 3), "this should not fit")
fmt.println(small_array.slice(&a))
}
[1, 2]
push_back_elems ¶
push_back_elems :: proc "contextless" (a: ^$A/Small_Array($N, $T), .. items: ..$T) -> bool {…}
Attempts to append all elements to the small-array returning false if there is not enough space to fit all of them.
Inputs
a: A pointer to the small-array
item: The item to append
..:
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
push_back_elems_example :: proc() {
a: small_array.Small_Array(100, int)
small_array.push_back_elems(&a, 0, 1, 2, 3, 4)
fmt.println(small_array.slice(&a))
}
[0, 1, 2, 3, 4]
push_front ¶
push_front :: proc "contextless" (a: ^$A/Small_Array($N, $T), item: $T) -> bool {…}
Attempts to add the given element at the beginning. This operation assumes that the small-array is not empty.
Note: Performing this operation will cause pointers obtained through get_ptr(_save) to reference incorrect elements.
Inputs
a: A pointer to the small-array
item: The item to append
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
push_front_example :: proc() {
a: small_array.Small_Array(2, int)
assert(small_array.push_front(&a, 2), "this should fit")
assert(small_array.push_front(&a, 1), "this should fit")
assert(!small_array.push_back(&a, 0), "this should not fit")
fmt.println(small_array.slice(&a))
}
[1, 2]
resize ¶
resize :: proc "contextless" (a: ^$A/Small_Array, length: int) {…}
Tries to resize the small-array to the specified length.
The new length will be:
- `length` if `length` <= capacity - capacity if length > capacity
Inputs
a: A pointer to the small-array
length: The new desired length
Example:
import "core:container/small_array"
import "core:fmt"
resize_example :: proc() {
a: small_array.Small_Array(5, int)
small_array.push_back(&a, 1)
small_array.push_back(&a, 2)
fmt.println(small_array.slice(&a))
small_array.resize(&a, 1)
fmt.println(small_array.slice(&a))
small_array.resize(&a, 100)
fmt.println(small_array.slice(&a))
}
[1, 2] [1] [1, 2, 0, 0, 0]
set ¶
set :: proc "contextless" (a: ^$A/Small_Array($N, $T), index: int, item: $T) {…}
Set the element at the specified position to the given value. This operation assumes that the small-array is large enough.
This will result in:
- the value being set if 0 <= index < capacity - 'crash' otherwise
Inputs
a: A pointer to the small-array
index: The position of the item to set
value: The value to set the element to
Example:
import "core:container/small_array"
import "core:fmt"
set_example :: proc() {
a: small_array.Small_Array(5, rune)
small_array.push_back(&a, 'A')
small_array.push_back(&a, 'B')
fmt.println(small_array.slice(&a))
// updates index 0
small_array.set(&a, 0, 'Z')
fmt.println(small_array.slice(&a))
// updates to a position x, where
// len <= x < cap are not visible since
// the length of the small-array remains unchanged
small_array.set(&a, 2, 'X')
small_array.set(&a, 3, 'Y')
small_array.set(&a, 4, 'Z')
fmt.println(small_array.slice(&a))
// resizing makes the change visible
small_array.resize(&a, 100)
fmt.println(small_array.slice(&a))
}
[A, B] [Z, B] [Z, B] [Z, B, X, Y, Z]
slice ¶
slice :: proc "contextless" (a: ^$A/Small_Array($N, $T)) -> []$T {…}
Returns a slice of the data.
Inputs
a: The pointer to the small-array
Returns the slice
Example:
import "core:container/small_array"
import "core:fmt"
slice_example :: proc() {
print :: proc(a: ^small_array.Small_Array($N, int)) {
for item in small_array.slice(a) {
fmt.println(item)
}
}
a: small_array.Small_Array(5, int)
small_array.push_back(&a, 1)
small_array.push_back(&a, 2)
print(&a)
}
1 2
space ¶
space :: proc "contextless" (a: $A/Small_Array) -> int {…}
Returns how many more items the small-array could fit.
Inputs
a: The small-array
Returns the number of unused slots
unordered_remove ¶
unordered_remove :: proc "contextless" (a: ^$A/Small_Array($N, $T), index: int, loc := #caller_location) {…}
Removes the element at the specified index without retaining order.
Inputs
a: A pointer to the small-array
index: The position of the element to remove
Example:
import "core:container/small_array"
import "core:fmt"
unordered_remove_example :: proc() {
a: small_array.Small_Array(4, int)
small_array.push(&a, 0, 1, 2, 3)
fmt.println("BEFORE:", small_array.slice(&a))
small_array.unordered_remove(&a, 1)
fmt.println("AFTER :", small_array.slice(&a))
}
BEFORE: [0, 1, 2, 3] AFTER : [0, 3, 2]
Procedure Groups
push ¶
push :: proc{ push_back, push_back_elems, }
Tries to append the element(s) to the small-array.
Inputs
a: A pointer to the small-array
item: The item to append
..:
Returns true if there was enough space to fit the element, false otherwise
Example:
import "core:container/small_array"
import "core:fmt"
push_example :: proc() {
a: small_array.Small_Array(100, int)
small_array.push(&a, 0)
small_array.push(&a, 1, 2, 3, 4)
fmt.println(small_array.slice(&a))
}
[0, 1, 2, 3, 4]
Source Files
Generation Information
Generated with odin version dev-2025-04 (vendor "odin") Windows_amd64 @ 2025-04-15 11:45:54.538914800 +0000 UTC