From 969435d08fe71998cd4a2e9973a8bf33c30d6515 Mon Sep 17 00:00:00 2001
From: marina <138340846+bt3gl-cryptographer@users.noreply.github.com>
Date: Tue, 1 Aug 2023 14:44:37 -0700
Subject: [PATCH] Update README.md

---
 queues/README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 84 insertions(+), 3 deletions(-)

diff --git a/queues/README.md b/queues/README.md
index da488aa..141955e 100644
--- a/queues/README.md
+++ b/queues/README.md
@@ -2,17 +2,98 @@
 
 <br>
 
-* first in, first out structures (FIFO), i.e., items are removed at the same order they are added.
-* queues can be implemented with two arrays or a dynamic array (linked list), as long as items are added and removed from opposite sides.
+* queues are **first in, first out structures (FIFO)** (i.e., items are removed at the same order they are added) that can be implemented with two arrays or a dynamic array (linked list), as long as items are added and removed from opposite sides.
 * if implemented with a dynamic array, a more efficient solution is to use a circular queue (ring buffer), i.e. a fixed-size array and two pointers to indicate the starting and ending positions. an advantage of circular queues is that we can use the spaces in front of the queue. in a normal queue, once the queue becomes full, we cannot insert the next element even if there is a space in front of the queue. but using the circular queue, we can use the space to store new values.
 * queues are often used in breath-first search (where you store a list of nodes to be processed) or when implementing a cache.
 
 
+<br>
+
+---
+
+### designing a circular queue
+
+<br>
+
+* a circular queue can be built with either arrays or linked lists (nodes). to build a ring with a fixed size array, any of the elements could be considered as the head.
+* as long as we know the length of the queue, we can instantly locat its tails based on this formula:
+
+```
+tail_index = (head_index + queue_length - 1) % queue_capacity
+```
+
+<br>
+
+* here is an example of an implementation using a "fixed-sized" array (sort of):
+
+<br>
+
+```python
+class CircularQueue:
+
+    def __init__(self, k: int):
+        self.head = -1
+        self.tail = -1
+        self.size = k
+        self.queue = [None] * self.size
+        
+    def _get_next_position(self, end) -> int:
+        return (end + 1) % self.size
+        
+    def enQueue(self, value: int) -> bool:
+
+        if self.is_full():
+            return False
+
+        if self.is_empty() :
+            self.head = 0;
+        
+        self.tail = self._get_next_position(self.tail)
+        self.queue[self.tail] = value
+
+        return True
+
+    def deQueue(self) -> bool:
+
+        if self.is_empty():
+            return False
+
+        if self.head == self.tail:
+            self.head = -1
+            self.tail = -1
+            return True
+        
+        self.head = self._get_next_position(self.head)
+
+        return True
+
+    def front(self) -> int:
+        if self.is_empty():
+            return -1
+        return self.queue[self.head]
+        
+    def rear(self) -> int:
+        if self.is_empty():
+            return -1
+        return self.queue[self.tail]
+        
+    def is_empty(self) -> bool:
+        return self.head == -1
+
+    def is_full(self) -> bool:
+        return self._get_next_position(self.tail) == self.head
+```
+
+<br>
+
+* note that this queue is not thread-safe: the data structure could be corrupted in a multi-threaded environment (as race-condition could occur). to mitigate this problem, one could add the protection of a lock.
+
+
 <br>
 
 ----
 
-### examples
+### some examples in this directory
 
 <br>