Queue¶

⏱ Time-Complexity¶

The following table sums up all the different public functionality in this class and also provides the worst-case time complexity along side with the optimal time complexity that I will try to reach in future releases Insha’Allah.

☕️ API¶

Here are all of the public methods that can be used with Queue() objects:

class extra.lists.queue.Queue(max_capacity=inf)¶

A queue is a close cousin of the stack, as a queue is a collection of objects that are inserted and removed according to the first-in, first-out (FIFO) principle. That is, elements can be inserted at any time, but only the element that has been in the queue the longest can be next removed. We usually say that elements enter a queue at the back and are removed from the front.

__init__(max_capacity=inf)¶

Creates a Queue() object!!

Parameters:	max_capacity (int) – It’s a positive integer representing the maximum number of elements a Queue() should contain (Default: inf).
Raises:	TypeError: If the type of max_capacity isn’t int or float. ValueError: If the given value of max_capacity is less than zero.

Example

>>> q = Queue()
>>> type(q)
<class 'extra.lists.queue.Queue'>
>>> q._max_capacity
inf

You can define the maximum capacity for your own instance:

>>> q = Queue(10)
>>> q._max_capacity
10

Note

If you passed a float number as the maximum capacity, then the value that get assigned is the rounding of that number:

>>> q = Queue(10.6)
>>> q._max_capacity
11

__len__()¶

Gets the length of the Queue() instance in constant time.

Returns:	The length of the Queue() instance. By Length, I mean the number of nodes of in the instance.
Return type:	int

Examples

>>> q = Queue()
>>> len(q)
0
>>> q.enqueue(1)
>>> q.enqueue(2)
>>> q.enqueue(3)
>>> len(q)
3

__repr__()¶

Represents the Queue() instance as a string.

Returns:	The string-representation of the Queue() instance.
Return type:	str

Example

>>> q = Queue()
>>> q.enqueue(10)
>>> q.enqueue(20)
>>> q
─┬────┬────┬─
⟶│ 20 │ 10 │⟶
─┴────┴────┴─

clear()¶

Removes all objects within the Queue() instance in constant time.

Example

>>> q = Queue()
>>> q.enqueue(1)
>>> q.enqueue(2)
>>> q.enqueue(3)
>>> q
─┬───┬───┬───┬─
⟶│ 3 │ 2 │ 1 │⟶
─┴───┴───┴───┴─
>>> len(q)
3
>>> q.clear()
>>> q
─┬
⟶│
─┴
>>> len(q)
0

Note

When you clear the Queue() instance, the max_capacity of the cleared instance remains the same as the one before.

dequeue()¶

Pops the first inserted item from the Queue() in constant time.

Returns:	The Queue() instance’s first item.
Return type:	object
Raises:	UserWarning: – If the Queue() instance is empty!!

Example

>>> q = Queue()
>>> q.dequeue()
UserWarning: Dequeuing from empty `extra.Queue()`!!
>>> q.enqueue(10)
>>> q.enqueue(20)
>>> q
─┬────┬────┬─
⟶│ 20 │ 10 │⟶
─┴────┴────┴─
>>> q.dequeue()
10
>>> q
─┬────┬─
⟶│ 20 │⟶
─┴────┴─

enqueue(item)¶

Inserts the given item to end of the Queue(), it does that in constant time.

Parameters:	item (object) – The python object to be pushed to the Queue().
Raises:	UserWarning: – If the Queue() instance was full!! By “full”, I mean the number of items in the Queue() equals to the assigned maximum capacity. ValueError: – If the given item is None. TypeError: – If the given item is an instance of Extra.

Example

>>> q = Queue(max_capacity=2)
>>> q
─┬
⟶│
─┴
>>> q.enqueue(1)
>>> q.enqueue(2)
>>> q
─┬───┬───┬─
⟶│ 2 │ 1 │⟶
─┴───┴───┴─
>>> q.enqueue(3)
UserWarning: Enqueuing to a full `extra.Queue()` could lead to             missing values!!
>>> q
─┬───┬───┬─
⟶│ 3 │ 2 │⟶
─┴───┴───┴─

is_empty()¶

Checks if Queue() instance is empty or not in constant time.

Returns:	A boolean flag showing if the Queue() instance is empty or not. True shows that this instance is empty and False shows it’s not empty.
Return type:	bool

Example

>>> q = Queue()
>>> q.is_empty()
True
>>> q.enqueue(5)
>>> q.is_empty()
False

is_full()¶

Checks if Queue() instance is at full-capacity in constant time.

Returns:	A boolean flag showing if the Queue() instance is full or not. True shows that this instance is full and False shows it’s not full.
Return type:	bool

Example

>>> q = Queue(max_capacity=2)
>>> q.is_full()
False
>>> q.enqueue(5)
>>> q.is_full()
False
>>> q.enqueue(10)
>>> q.is_full()
True

top()¶

Returns the first item inserted to the Queue() instance in constant time.

Returns:	The Queue() instance’s first inserted item.
Return type:	object
Raises:	IndexError: – If the Queue() instance is empty!!

Example

>>> q = Queue()
>>> q.top()
IndexError: Can't retrieve from an empty `extra.Queue()`!!
>>> q.enqueue(10)
>>> q.enqueue(20)
>>> q
─┬────┬────┬─
⟶│ 20 │ 10 │⟶
─┴────┴────┴─
>>> q.top()
10