Stack¶

⏱ 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 Stack() objects:

class extra.lists.stack.Stack(max_capacity=inf)¶

A stack is the simplest linear data structure where objects that are inserted and removed according to the last-in, first-out (LIFO) principle. A user may insert objects into a stack at any time, but may only access or remove the most recently inserted object that remains at, the so-called, top of the stack.

__init__(max_capacity=inf)¶

Creates a Stack() object!!

Parameters:	max_capacity (int) – It’s a positive integer representing the maximum number of elements a Stack() 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

>>> s = Stack()
>>> type(s)
<class 'extra.lists.stack.Stack'>
>>> s._max_capacity
inf

You can define the maximum capacity for your own instance:

>>> s = Stack(10)
>>> s._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:

>>> s = Stack(10.6)
>>> s._max_capacity
11

__len__()¶

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

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

Examples

>>> s = Stack()
>>> len(s)
0
>>> s.push(1)
>>> s.push(2)
>>> s.push(3)
>>> len(s)
3

__repr__()¶

Represents the Stack() instance as a string.

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

Example

>>> s = Stack()
>>> s.push(10)
>>> s.push(20)
>>> s
┌────┬────┬─
│ 10 │ 20 │
└────┴────┴─

clear()¶

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

Example

>>> s = Stack()
>>> s.push(1)
>>> s.push(2)
>>> s.push(3)
>>> s
┌───┬───┬───┬─
│ 1 │ 2 │ 3 │
└───┴───┴───┴─
>>> len(s)
3
>>> s.clear()
>>> s
┌─
│
└─
>>> len(s)
0

Note

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

is_empty()¶

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

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

Example

>>> s = Stack()
>>> s.is_empty()
True
>>> s.push(5)
>>> s.is_empty()
False

is_full()¶

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

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

Example

>>> s = Stack(max_capacity=2)
>>> s.is_full()
False
>>> s.push(5)
>>> s.is_full()
False
>>> s.push(10)
>>> s.is_full()
True

peek()¶

Returns the top item of the Stack() instance in constant time.

Returns:	The Stack() instance’s top item which is the last item to be pushed to the instance.
Return type:	object
Raises:	IndexError: – If the Stack() instance is empty!!

Example

>>> s = Stack()
>>> s.peek()
IndexError: Can't peek from an empty `extra.Stack()`!!
>>> s.push(10)
>>> s.push(20)
>>> s
┌────┬────┬─
│ 10 │ 20 │
└────┴────┴─
>>> s.peek()
20

pop()¶

Pops the top item from the Stack() in constant time.

Returns:	The Stack() instance’s top item which is the last item to be pushed to the instance.
Return type:	object
Raises:	UserWarning: – If the Stack() instance is empty!!

Example

>>> s = Stack()
>>> s.pop()
UserWarning: Popping from empty `extra.Stack()`!!
>>> s.push(10)
>>> s.push(20)
>>> s
┌────┬────┬─
│ 10 │ 20 │
└────┴────┴─
>>> s.pop()
20
>>> s
┌────┬─
│ 10 │
└────┴─

push(item)¶

Pushs the given item to the Stack() in constant time. This item will be at the top of the Stack().

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

Example

>>> s = Stack(max_capacity=2)
>>> s
┌─
│
└─
>>> s.push(1)
>>> s.push(2)
>>> s
┌───┬───┬─
│ 1 │ 2 │
└───┴───┴─
>>> s.push(3)
OverflowError: Stackoverflow! Can't push into a full `extra.Stack()`!!