uSTL: Queue, Deque and Pair

examples/udeque.md

@@ -0,0 +1,122 @@
+# 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 the length of the deque using the built-in len() function.
+
+```python
+d2 = UDeque(1, 2, 3, 4, 5)
+len(d2) # 5
+```
+
+## Reserve
+To reserve the deque's end and beginning, use the built-in `reserved()` function
+```python
+reserved(d2) # [5, 1]
+```
+
+> [!NOTE]
+> `reserved()` returns `[end, begin]`
+
+## Iteration
+`UDeque()` suppots iteration:
+```python
+for var in d2:
+    print(var)
+# 1
+# 2
+# 3
+# 4
+# 5
+```
+
+> [!NOTE]
+> After using `for` your deque will be empty:
+> ```python
+> print(d2) # []
+> ```

examples/upair.md

@@ -0,0 +1,72 @@
+# UPair
+
+## Introduction
+
+UDeque is class which is simplifying working with pair.
+It has many methods, properties, magic methods.
+
+Firstly, import `UPair` from `ufpy`
+```python
+from ufpy import UPair
+```
+
+## Create UPair
+
+For creating UPair you should use this code:
+```python
+p = UPair(first="first", second="second")
+```
+
+## Get first/second
+
+To get the first value you can use:
+```python
+p[0] # first
+p.first # first
+```
+
+To get the second value you can use:
+```python
+p[1] # second
+p.second # second
+```
+
+> [!NOTE]
+> 0 - the first value
+> 1 - the second value
+
+## Set first/second
+
+To set the first value you can use
+```python
+p.first = "FIRST" # FIRST
+```
+
+Use the same way to set the second value
+
+> [!NOTE]
+> Also you can use indexes:
+> ```python
+> p[0] = "FIRST"
+> p[1] = "SECOND"
+> ```
+> But it is undesirable to use
+
+## Get length of pair
+
+You can get the length of the pair using the built-in len() function.
+
+```python
+p2 = UPair(1, 2)
+len(p2) # 2
+```
+
+> [!NOTE]
+> If `first == None` and `second == "second"` `len()` returns 1
+> If `first == None` and `second == None` `len()` returns 0
+
+## Reserve
+To reserve the pair's the first and the second value, use the built-in `reserved()` function
+```python
+reserved(p2) # ["second", "first"]
+```

examples/uqueue.md

@@ -0,0 +1,78 @@
+# UQueue
+## Introduction
+
+UQueue is class which is simplifying working with queue.
+It has many methods, properties, magic methods.
+
+Firstly, import `UQueue` from `ufpy`
+```python
+from ufpy import UQueue
+```
+
+## Create UQueue
+
+For creating UQueue you should use this code:
+```python
+q = UQueue(1, 2, 3, 4, 5)
+```
+
+## Get head
+
+To get head of the queue use:
+```python
+q.head # 5
+```
+
+## Add value
+
+To add value you can use
+```python
+q.push(6) # [1, 2, 3, 4, 5, 6]
+```
+
+## Set head
+
+To set end you can use
+```python
+q.set_head(7) # [1, 2, 3, 4, 5, 7]
+```
+
+## Delete value
+
+For deleting the first element use
+```python
+q.pop() # [2, 3, 4, 5, 7]
+```
+
+## Get length of queue
+
+You can get the length of the queue using the built-in len() function.
+
+```python
+q2 = UQueue(1, 2, 3, 4, 5)
+len(q2) # 5
+```
+
+## Reserve
+To reserve the queue's end and beginning, use the built-in `reserved()` function
+```python
+reserved(q2) # [5, 4, 3, 2, 1]
+```
+
+## Iteration
+`UQueue()` suppots iteration:
+```python
+for var in q2:
+    print(var)
+# 1
+# 2
+# 3
+# 4
+# 5
+```
+
+> [!NOTE]
+> After using `for` your queue will be empty:
+> ```python
+> print(q2) # []
+> ```

ufpy/udeque.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+from typing import TypeVar, Generic, Any
+
+__all__ = (
+    "UDeque",
+)
+
+VT = TypeVar("VT")
+
+class UDeque(Generic[VT]):
+    def __init__(self, *__list):
+        self.__list = list(__list)
+
+    def addend(self, value: VT) -> VT:
+        if self:
+            self.__list.append(value)
+            return value
+        else:
+            raise IndexError("index out of range")
+
+    def addbegin(self, value: VT) -> VT:
+        if self:
+            self.__list.insert(0, value)
+            return value
+        else:
+            raise IndexError("index out of range")
+
+    def popend(self) -> VT:
+        if self:
+            return self.__list.pop()
+        else:
+            raise IndexError("index out of range")
+
+    def popbegin(self) -> VT:
+        if self:
+            return self.__list.pop(0)
+        else:
+            raise IndexError("index out of range")
+
+    def setend(self, value: VT) -> VT:
+        if self:
+            self[-1] = value
+            return value
+        else:
+            raise IndexError("index out of range")
+
+    def setbegin(self, value: VT) -> VT:
+        if self:
+            self[0] = value
+            return value
+        else:
+            raise IndexError("index out of range")
+
+    def end(self) -> Any:
+        return self.__list[-1] if self else None
+
+    def begin(self) -> Any:
+        return self.__list[0] if self else 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)
+
+    def __iter__(self) -> UDeque:
+        return self
+
+    def __next__(self) -> VT:
+        if self.is_empty():
+            raise StopIteration
+        else:
+            value = self.popbegin()
+            return value