SwiftQueue

A first-in-first-out queue.

The SwiftQueue type stores its elements in a circular buffer in one or two contiguous regions of memory. Add elements to the queue by calling append(_:) and remove elements in the order they were added by calling removeFirst() on a non-empty queue or popFirst() on a possibly-empty queue.

Subscript access allows access to the elements of the queue in the order that they were added.

Features

Conforms to the same protocols as Array including Collection and RangeReplaceableCollection.
Uses a highly-performant circular buffer backing.
append(_:) and popFirst() are both O(1) operations.
Significantly better cache-locality than linked-list implementations.
Thoroughly documented source code.

Documentation

The source code contains extensive documentation of both public and internal functions. SwiftQueue does not add extra methods for push(_:), pop() and peek() instead using the existing methods and properties defined in Swift's various protocols:

append(_:) to add an element to the end of the queue
popFirst() -> Element? to remove the first element in the queue or return nil if empty
first: Element? to access the first element in the queue without removing it.

Initialization

SwiftQueue can be initialized just like an Array instance.

A queue with Int elements can be created as follows:

var queue = SwiftQueue<Int>()
...
var queue = SwiftQueue([1, 3, 5, 8, 9])
...
var queue = SwiftQueue( 2 ..< 14 )
...
var queue: SwiftQueue = [1, 2, 4, 3, 6]

Adding, removing, and accessing elements

Elements can be added, removed and accessed using standard methods and properties:

var queue: SwiftQueue = ["I", "love", "to", "queue"]

queue.append("!")           // queue is now ["I", "love", "to", "queue", "!"]
print(queue.removeFirst())  // prints "I"
                            // queue is now ["love", "to", "queue", "!"]

print(queue.first!)         // prints "love"

for element in queue {
    print(element)          // prints "to", "queue", "!"
}

print(queue[1])             // prints "queue"

while let element = queue.popFirst() {
    print(element)          // prints "to", "queue", "!"
}

print(queue.isEmpty)        // prints "true"

Other operations

Other methods and properties can be used like with Array:

let queue: SwiftQueue = [1.0, 3.2, 3.5, 8.0]

queue.count             // returns 4

queue.last              // returns Optional(8.0)

Performance

For operations such as append(_:), performance of SwiftQueue is similar to Array. The operations removeFirst() and removeFirst(k) have complexity O(1) and O(k) respectively, instead of O(n), where n is the length of the collection. Additionally, when the number of calls to append(_:) and removeFirst() are balanced and the length of the queue remains stable, memory locality is maintained, thereby improving cache performance.

peteraisher / SwiftQueue