Module queues

Implementation of a queue. The underlying implementation uses a seq.

None of the procs that get an individual value from the queue can be used on an empty queue. If compiled with boundChecks option, those procs will raise an IndexError on such access. This should not be relied upon, as -d:release will disable those checks and may return garbage or crash the program.

As such, a check to see if the queue is empty is needed before any access, unless your program logic guarantees it indirectly.

proc foo(a, b: Positive) =  # assume random positive values for `a` and `b`
  var q = initQueue[int]()  # initializes the object
  for i in 1 ..< a: q.add i  # populates the queue
  
  if b < q.len:  # checking before indexed access
    echo "The element at index position ", b, " is ", q[b]
  
  # The following two lines don't need any checking on access due to the
  # logic of the program, but that would not be the case if `a` could be 0.
  assert q.front == 1
  assert q.back == a
  
  while q.len > 0:  # checking if the queue is empty
    echo q.pop()

Note: For inter thread communication use a Channel instead.

Types

Queue {...}{.deprecated.}[T] = object
  data: seq[T]
  rd, wr, count, mask: int
A queue.   Source Edit

Procs

proc initQueue[T](initialSize: int = 4): Queue[T]

Create a new queue. Optionally, the initial capacity can be reserved via initialSize as a performance optimization. The length of a newly created queue will still be 0.

initialSize needs to be a power of two. If you need to accept runtime values for this you could use the nextPowerOfTwo proc from the math module.

  Source Edit
proc len[T](q: Queue[T]): int {...}{.inline.}
Return the number of elements of q.   Source Edit
proc front[T](q: Queue[T]): T {...}{.inline.}
Return the oldest element of q. Equivalent to q.pop() but does not remove it from the queue.   Source Edit
proc back[T](q: Queue[T]): T {...}{.inline.}
Return the newest element of q but does not remove it from the queue.   Source Edit
proc `[]`[T](q: Queue[T]; i: Natural): T {...}{.inline.}
Access the i-th element of q by order of insertion. q[0] is the oldest (the next one q.pop() will extract), q[^1] is the newest (last one added to the queue).   Source Edit
proc `[]`[T](q: var Queue[T]; i: Natural): var T {...}{.inline.}
Access the i-th element of q and returns a mutable reference to it.   Source Edit
proc `[]=`[T](q: var Queue[T]; i: Natural; val: T) {...}{.inline.}
Change the i-th element of q.   Source Edit
proc contains[T](q: Queue[T]; item: T): bool {...}{.inline.}
Return true if item is in q or false if not found. Usually used via the in operator. It is the equivalent of q.find(item) >= 0.
if x in q:
  assert q.contains x
  Source Edit
proc add[T](q: var Queue[T]; item: T)
Add an item to the end of the queue q.   Source Edit
proc pop[T](q: var Queue[T]): T {...}{.inline, discardable.}
Remove and returns the first (oldest) element of the queue q.   Source Edit
proc enqueue[T](q: var Queue[T]; item: T)
Alias for the add operation.   Source Edit
proc dequeue[T](q: var Queue[T]): T
Alias for the pop operation.   Source Edit
proc `$`[T](q: Queue[T]): string
Turn a queue into its string representation.   Source Edit

Iterators

iterator items[T](q: Queue[T]): T
Yield every element of q.   Source Edit
iterator mitems[T](q: var Queue[T]): var T
Yield every element of q.   Source Edit
iterator pairs[T](q: Queue[T]): tuple[key: int, val: T]
Yield every (position, value) of q.   Source Edit