uSTL: Queue, Deque and Pair

examples/udeque.md

@@ -0,0 +1,105 @@
+# UDeque
+
+## Introduction
+
+UDeque is class which is simplifying working with deque.
+It has many methods, properties, magic methods.
+
+Firstly, import `UDeque` from `ufpy`
+```python
+from ufpy import UDeque
+```
+
+## Create UDeque
+
+For creating UDeque you should use this code:
+```python
+d = UDeque((1, 2, 3, 4, 5))
+```
+
+## Get end/begin
+
+To get end you can use:
+```python
+d[0] # 1
+d.end() # 1
+```
+
+To get begin you can use:
+```python
+d[1] # 5
+d.begin() # 5
+```
+
+> [!NOTE]
+> 0 - first element
+> 1 - last element
+
+## Add end/begin
+
+To add end you can use
+```python
+d.addend(6) # [1, 2, 3, 4, 5, 6]
+```
+
+To add begin you can use
+```python
+d.addbegin(0) # [0, 1, 2, 3, 4, 5, 6]
+```
+
+## Set end/begin
+
+To set end you can use
+```python
+d.setend(7) # [0, 1, 2, 3, 4, 5, 7]
+```
+
+To set begin you can use
+```python
+d.setbegin(7) # [7, 1, 2, 3, 4, 5, 7]
+```
+> [!NOTE]
+> Also you can use indexes:
+> ```python
+> d[0] = 1 # [1, 1, 2, 3, 4, 5, 7]
+> d[1] = 1 # [1, 1, 2, 3, 4, 5, 1]
+> ```
+> But it is undesirable to use
+
+## Delete end/begin
+
+For deleting end use
+```python
+d.popend() # [7, 1, 2, 3, 4, 5]
+```
+
+For deleting begin use
+```python
+d.popbegin(7) # [1, 2, 3, 4, 5]
+```
+
+> [!NOTE]
+> To delete end or begin you also can use `del`:
+> ```python
+> del d[0] # [2, 3, 4, 5]
+> del d[1] # [2, 3, 4]
+> ```
+> But it is undesirable to use
+
+## Get length of deque
+
+You can get length of dict using inbuilt `len()` function
+
+```python
+d2 = UDeque((1, 2, 3, 4, 5))
+len(d2) # 5
+```
+
+## Reserve
+To reserve deque's end and begin use inbuilt `reserved()` function
+```python
+reserved(d2) # [5, 1]
+```
+
+> [!NOTE]
+> `reserved()` returns `[end, begin]`

ufpy/udeque.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+from typing import TypeVar, Generic, Iterable, Any
+
+__all__ = (
+    "UDeque"
+)
+
+VT = TypeVar("VT")
+
+class UDeque(Generic[VT]):
+    def __init__(self, __list: Iterable[VT] = []):
+        self.__list = list(__list)
+
+    def addend(self, value: VT):
+        self.__list.append(value)
+
+    def addbegin(self, value: VT):
+        self.__list.insert(0, value)
+
+    def popend(self):
+        return self.__list.pop()
+
+    def popbegin(self):
+        return self.__list.pop(0)
+
+    def setend(self, value: VT):
+        self[1] = value
+
+    def setbegin(self, value: VT):
+        self[0] = value
+
+    def end(self) -> VT:
+        if self:
+            return self.__list[-1]
+        else:
+            return None
+
+    def begin(self) -> VT:
+        if self:
+            return self.__list[0]
+        else:
+            return None
+
+    def copy(self) -> UDeque:
+        return UDeque(self.__list.copy())
+
+    def is_empty(self) -> bool:
+        return len(self) == 0
+
+    def reversed(self) -> UDeque:
+        return self.__reversed__()
+
+    def __len__(self) -> int:
+        return len(self.__list)
+
+    def __nonzero__(self) -> bool:
+        return not self.is_empty()
+
+    def __getitem__(self, index: Any) -> VT:
+        if isinstance(index, int):
+            if index in (0, 1):
+                return self.__list[index]
+            else:
+                raise IndexError(f"{index} out of range (0, 1)")
+
+    def __setitem__(self, index: int, value: VT):
+        if isinstance(index, int):
+            if index == 0:
+                self.__list[index] = value
+            elif index == 1:
+                self.__list[-index] = value
+            else:
+                raise IndexError(f"{index} out of range (0, 1)")
+
+    def __delitem__(self, index: int):
+        if isinstance(index, int):
+            if index == 0:
+                del self.__list[index]
+            elif index == 1:
+                del self.__list[-index]
+            else:
+                raise IndexError(f"{index} out of range (0, 1)")
+
+    def __reversed__(self) -> UDeque:
+        return UDeque((self.end(), self.begin()))
+
+    def __str__(self) -> str:
+        return str(self.__list)