Misc.Queue module

A double queue.

Taken from Programming in Lua Queues and Double Queues and modified to not allow nil values, and returns nil if pop_first or pop_last is used when the queue is empty.

Usage

local Queue = require('__stdlib__/stdlib/misc/queue')
local q = Queue() -- create a new empty queue
q('my value') -- push a value onto the queue
q() -- pop the last value off the queue
game.print(#q) -- print the number of items in the queue

Functions

new(...) Constructs a new Queue object.
load(queue) Load global.queue or queues during on_load, as metatables are not persisted.
push_first(queue, value) Push a new element to the front of the queue.
push_last(queue, ...) Push a new element to the back of the queue.
push() Shortcut for Queue.push_last
push_at(queue, index, value) Push a new element to a specific location of the queue.
pop_first(queue) Retrieve the element at the front of the queue and remove it from the queue.
pop() Shortcut for Queue.pop_first
pop_at(queue, index) Pop an element at a specific location of the queue.
peek_at(queue, index) Peek at an element in the queue without disturbing the queue.
peek_first(queue) Return the element at the front of the queue and remove it from the queue.
peek() Shortcut for Queue.peek_first
pop_last(queue) Retrieve the element at the back of the queue and remove it from the queue.
peek_last(queue) Return the element at the back of the queue.
pop_and_push(queue) Returns the popped value and pushes back into the queue.
cycle(queue) Returns the queue after popping the last element and pushing it to the top.
find(queue, find) Gets the first index which matches the stored data.
sort(queue, func) sort and reorder the queue
is_empty(queue) Returns true if the given queue is empty.
size(queue) Returns the number of items in the queue.
count() Shortcut for Queue.size
next(queue, index, pop) Return the next element in the queue
rnext(queue, index, pop) Return the previous element in the queue
pairs(queue, pop) Iterate the queue forward
rpairs(queue, pop) Iterate the queue backwards

Functions

# new(...)

Constructs a new Queue object.

Parameters:
  • ... : mixed, values to push into the queue
Returns:
  • a new queue
# load(queue)

Load global.queue or queues during on_load, as metatables are not persisted.

This is only needed if you are using the queue as an object and storing it in global.

Parameters: Usage:
global.myqueue1 = Queue.new()
 script.on_load(function() Queue.load(global.myqueue))
# push_first(queue, value)

Push a new element to the front of the queue.

Parameters:
  • queue : (Queue) the queue to push an element to
  • value : (Mixed) the element to push
# push_last(queue, ...)

Push a new element to the back of the queue.

Parameters:
  • queue : (Queue) the queue to push an element to
  • ... : (Mixed) the element(s) to push
# push()

Shortcut for Queue.push_last

# push_at(queue, index, value)

Push a new element to a specific location of the queue.

Parameters:
  • queue : (Queue) the queue to push an element to
  • index : (number) the index to push to.
  • value : (Mixed) the element to push.
# pop_first(queue)

Retrieve the element at the front of the queue and remove it from the queue.

Parameters:
  • queue : (Queue) the queue to retrieve the element from
Returns:
  • (Mixed) value the element at the front of the queue
# pop()

Shortcut for Queue.pop_first

# pop_at(queue, index)

Pop an element at a specific location of the queue.

Parameters:
  • queue : (Queue) the queue to push an element to
  • index : (number) the index to push to.
Returns:
  • (Mixed) value the popped element.
# peek_at(queue, index)

Peek at an element in the queue without disturbing the queue.

Parameters:
  • queue : (Queue) the queue to peek at
  • index : (number) the index in the queue to peek at
Returns:
  • (Mixed) the value of the peeked element
# peek_first(queue)

Return the element at the front of the queue and remove it from the queue.

Parameters:
  • queue : (Queue) the queue to retrieve the element from
Returns:
  • (Mixed) the element at the front of the queue
# peek()

Shortcut for Queue.peek_first

# pop_last(queue)

Retrieve the element at the back of the queue and remove it from the queue.

Parameters:
  • queue : (Queue) the queue to retrieve the element from
Returns:
  • (Mixed) the element at the back of the queue
# peek_last(queue)

Return the element at the back of the queue.

Parameters:
  • queue : (Queue) the queue to retrieve the element from
Returns:
  • (Mixed) the element at the back of the queue
# pop_and_push(queue)

Returns the popped value and pushes back into the queue.

Parameters:
  • queue : (Queue) the queue
Returns:
  • Mixed the value that was popped.
# cycle(queue)

Returns the queue after popping the last element and pushing it to the top.

Parameters:
  • queue : (Queue) the queue
Returns:
  • the queue
# find(queue, find)

Gets the first index which matches the stored data.

does not compare inside tables.

Parameters:
  • queue
  • find
# sort(queue, func)

sort and reorder the queue

Parameters:
  • queue
  • func
# is_empty(queue)

Returns true if the given queue is empty.

Parameters:
  • queue : (Queue) the queue to check
Returns:
  • (boolean) true if empty, false otherwise
# size(queue)

Returns the number of items in the queue.

Parameters:
  • queue : (Queue) the queue to check
Returns:
  • (number) the number of items in the queue
# count()

Shortcut for Queue.size

# next(queue, index, pop)

Return the next element in the queue

Parameters:
  • queue : (Queue) the queue to check
  • index : (number or nil) if nil return the first value, else return the next index value
  • pop : (boolean) pop the value off the queue
Returns:
  • (number or nil) the index
  • (Mixed or nil) the value at queue index
# rnext(queue, index, pop)

Return the previous element in the queue

Parameters:
  • queue : (Queue) the queue to check
  • index : (number or nil) if nil return the last value, else return the previous index value
  • pop : (boolean) pop the value off the queue
Returns:
  • (number or nil) the index
  • (Mixed or nil) the value at queue index
# pairs(queue, pop)

Iterate the queue forward

Parameters:
  • queue
  • pop
# rpairs(queue, pop)

Iterate the queue backwards

Parameters:
  • queue
  • pop