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

Alias for push_back

Alias for push_back_elems

Returns the capacity of the small-array.

Inputs

• a: The small-array

Returns the capacity

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 : []

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

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

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]

Returns the amount of items in the small-array.

Inputs

• a: The small-array

Returns

• the amount of items in the array

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]

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]

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]

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

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]

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

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]

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]

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]

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 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]

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

Returns how many more items the small-array could fit.

Inputs

• a: The small-array

Returns

• the number of unused slots

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]

Alias for push

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]