container_queue

Queue is a dynamically resizable double-ended queue/ring-buffer.

Being double-ended means that either end may be pushed onto or popped from across the same block of memory, in any order, thus providing both stack and queue-like behaviors in the same data structure.

Internal growing procedure

Get the element at the back of the queue.

This will raise a bounds checking error if the queue is empty.

Get a pointer to the element at the back of the queue.

This will raise a bounds checking error if the queue is empty.

Return the capacity of the queue.

Reset the queue's length and offset to zero, letting it write new elements over old memory, in effect clearing the accessible contents.

Consume n elements from the back of the queue.

This will raise a bounds checking error if the queue does not have enough elements.

Consume n elements from the front of the queue.

This will raise a bounds checking error if the queue does not have enough elements.

Delete memory that has been dynamically allocated from a Queue that was setup with init.

Note that this procedure should not be used on queues setup with init_from_slice or init_with_contents, as neither of those procedures keep track of the allocator state of the underlying backing slice.

Get the element at the front of the queue.

This will raise a bounds checking error if the queue is empty.

Get a pointer to the element at the front of the queue.

This will raise a bounds checking error if the queue is empty.

Get the element at index i.

This will raise a bounds checking error if i is an invalid index.

Get a pointer to the element at index i.

This will raise a bounds checking error if i is an invalid index.

Initialize a Queue with a starting capacity and an allocator.

Initialize a Queue from a fixed backing slice into which modifications are made directly.

The contents of the backing will be overwritten as items are pushed onto the Queue. Any previous contents will not be available through the API but are not explicitly zeroed either.

Note that procedures which need space to work (push_back, ...) will fail if the backing slice runs out of space.

Initialize a Queue from a fixed backing slice into which modifications are made directly.

The contents of the queue will start out with all of the elements in backing, effectively creating a full queue from the slice. As such, no procedures will be able to add more elements to the queue until some are taken off.

Return the length of the queue.

Pop an element from the back of the queue.

This will raise a bounds checking error if the queue is empty.

Example:

import "base:runtime"
import "core:container/queue"

// This demonstrates stack behavior (First-In Last-Out) at the far end of the data array.
main :: proc() {
	q: queue.Queue(int)
	queue.init(&q)
	queue.push_front(&q, 1)
	queue.push_front(&q, 2)
	queue.push_front(&q, 3)
	// q.data is now [..., 3, 2, 1]
	log.infof("%#v", q)
	assert(queue.pop_front(&q) == 3)
	assert(queue.pop_front(&q) == 2)
	assert(queue.pop_front(&q) == 1)
}

Pop an element from the back of the queue if one exists and return true. Otherwise, return a nil element and false.

Pop an element from the front of the queue

This will raise a bounds checking error if the queue is empty.

Pop an element from the front of the queue if one exists and return true. Otherwise, return a nil element and false.

Push an element to the back of the queue.

If there is no more space left and allocation fails to get more, this will return false with an Allocator_Error.

Example:

import "base:runtime"
import "core:container/queue"

// This demonstrates typical queue behavior (First-In First-Out).
main :: proc() {
	q: queue.Queue(int)
	queue.init(&q)
	queue.push_back(&q, 1)
	queue.push_back(&q, 2)
	queue.push_back(&q, 3)
	// q.data is now [1, 2, 3, ...]
	assert(queue.pop_front(&q) == 1)
	assert(queue.pop_front(&q) == 2)
	assert(queue.pop_front(&q) == 3)
}

Push many elements at once to the back of the queue.

If there is not enough space left and allocation fails to get more, this will return false with an Allocator_Error.

Push an element to the front of the queue.

If there is no more space left and allocation fails to get more, this will return false with an Allocator_Error.

Example:

import "base:runtime"
import "core:container/queue"

// This demonstrates stack behavior (First-In Last-Out).
main :: proc() {
	q: queue.Queue(int)
	queue.init(&q)
	queue.push_back(&q, 1)
	queue.push_back(&q, 2)
	queue.push_back(&q, 3)
	// q.data is now [1, 2, 3, ...]
	assert(queue.pop_back(&q) == 3)
	assert(queue.pop_back(&q) == 2)
	assert(queue.pop_back(&q) == 1)
}

Reserve enough space in the queue for at least the specified capacity.

This may return an error if allocation failed.

Set the element at index i to val.

This will raise a bounds checking error if i is an invalid index.

Shrink a queue's dynamically allocated array.

This has no effect if the queue was initialized with a backing slice.

Return the remaining space in the queue.

This will be cap() - len().