core/container/small_array package | Odin Programming Language

Deprecation Notice: Prefer using `[dynamic; N]T` (fixed capacity dynamic arrays). 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) } Output: Hellope

Collection Info

Collection: core
Path: container/small_array
Entries: 28

Constants 0

Types 1

Procedures 25

Jump to Procedures

append_elem append_elems cap clear consume get get_ptr get_ptr_safe get_safe inject_at len non_zero_resize ordered_remove pop_back pop_back_safe pop_front +9 more

Procedure Groups 2

Jump to Procedure Groups

Variables 0

Source Files

Types

1

Small_Array #

Small_Array :: Small_Array

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) }

Procedures

25

append_elem #

append_elem :: 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)) } Output: [1, 2]

append_elems #

append_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)) } Output: [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)) } Output: 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)) } Output: BEFORE: [0, 1, 2] AFTER : [0]

get #

get :: proc "contextless" (a: $A/Small_Array($N, $T), index: int) -> $$deferred_return {…}

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 - raise a bounds check error if capacity <= index - the previous value if len < index < capacity, which defauls to T's zero value. e.g. if you call `small_array.push(&a, 0, 1, 2)`, and `i := pop_back(&a)`, then `get(a, 2)` will return the earlier value `2` at that location. See also `get_safe`, which returns T's zero value and `false` if `index` is out of bounds. **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) -> $$deferred_return {…}

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 - raise a bounds check error if capacity <= index - a pointer to the previous value if len < index < capacity, which defauls to T's zero value. e.g. if you call `small_array.push(&a, 0, 1, 2)`, and `i := pop_back(&a)`, then `get_ptr(a, 2)` will return a pointer to the slot containing the earlier value `2` at that location. See also `get_ptr_safe`, which returns a nil pointer, and `false` if `index` is out of bounds. **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 "contextless" (a: ^$A/Small_Array($N, $T), index: int) -> ($$deferred_return, 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 "contextless" (a: $A/Small_Array($N, $T), index: int) -> ($$deferred_return, 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') } Output: 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(_safe) 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)) } Output: [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

non_zero_resize #

non_zero_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" non_zero_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.non_zero_resize(&a, 1) fmt.println(small_array.slice(&a)) small_array.non_zero_resize(&a, 100) fmt.println(small_array.slice(&a)) } Output: [1, 2] [1] [1, 2, 0, 0, 0]

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(_safe) 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)) } Output: BEFORE: [0, 1, 2, 3] AFTER : [0, 2, 3]

pop_back #

pop_back :: proc(a: ^$A/Small_Array($N, $T), loc := #caller_location) -> $$deferred_return {…}

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)) } Output: BEFORE: [0, 1, 2] AFTER: [0, 1]

pop_back_safe #

pop_back_safe :: proc "contextless" (a: ^$A/Small_Array($N, $T)) -> (item: $$deferred_return, 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) -> $$deferred_return {…}

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(_safe) 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)) } Output: BEFORE: [0, 1, 2] AFTER: [1, 2]

pop_front_safe #

pop_front_safe :: proc "contextless" (a: ^$A/Small_Array($N, $T)) -> (item: $$deferred_return, 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(_safe) 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)) } Output: [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)) } Output: [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(_safe) 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)) } Output: [1, 2]

resize #

resize :: proc "contextless" (a: ^$A/Small_Array($N, $T), length: int) {…}

Tries to resize the small-array to the specified length. The memory of added elements will be zeroed out. 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)) } Output: [1, 2] [1] [1, 0, 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.non_zero_resize(&a, 100) fmt.println(small_array.slice(&a)) } Output: [A, B] [Z, B] [Z, B] [Z, B, X, Y, Z]

slice #

slice :: proc "contextless" (a: ^$A/Small_Array($N, $T)) -> $$deferred_return {…}

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) } Output: 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)) } Output: BEFORE: [0, 1, 2, 3] AFTER : [0, 3, 2]

Procedure Groups

2

append #

append :: proc{
	append_elem,
	push_back_elems,
}

Alias for `push`

push #

push :: proc{
	append_elem,
	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)) } Output: [0, 1, 2, 3, 4]