UDict: final get() + all methods + magic methods to __bool__()

docs/useful_classes/udict.md

@@ -17,7 +17,7 @@ tags:
 
 ## class UDict[KT, VT, CDV]
 
-```python
+```py
 class UDict(dictionary: AnyDict[KT, VT]) # (1)!
 class UDict(dictionary: AnyDict[KT, VT], *, default: CDV)
 class UDict(**kwargs: VT)
@@ -56,7 +56,7 @@ UDict's dictionary.
     You can use UDict to set dictionary
 
     !!! example
-        ```python
+        ```py
         d.dictionary = UDict({1: 7})
         ```
 
@@ -65,7 +65,7 @@ UDict's dictionary.
 UDict's keys
 
 !!! example
-    ```python
+    ```py
     print(d.keys)
     d.keys = [1, 2]
     ```
@@ -74,7 +74,7 @@ UDict's keys
     You can use tuples to set keys
 
     !!! example
-        ```python
+        ```py
         d.keys = 1, 2
         ```
 
@@ -83,7 +83,7 @@ UDict's keys
 UDict's values
 
 !!! example
-    ```python
+    ```py
     print(d.values)
     d.values = [7, 2]
     ```
@@ -92,7 +92,7 @@ UDict's values
     You can use tuples to set values
 
     !!! example
-        ```python
+        ```py
         d.values = 7, 2
         ```
 
@@ -101,7 +101,7 @@ UDict's values
 UDict's items.
 
 !!! example
-    ```python
+    ```py
     print(d.items)
     d.items = [(1, 7), (2, 2)]
     ```
@@ -110,7 +110,7 @@ UDict's items.
     You can use tuples to set items or you can use tuples or lists with lists
 
     !!! example
-        ```python
+        ```py
         d.items = (1, 7), (2, 2)
         d.items = [1, 7], [2, 2]
         ```
@@ -120,7 +120,7 @@ UDict's items.
 UDict's default value
 
 !!! example
-    ```python
+    ```py
     print(d.default)
     d.default = 'null'
     ```
@@ -133,13 +133,13 @@ Reverses UDict and returns it. (1)
 1.  !!! question "How UDict is being reversing?"
 
         Just is being reversing items  
-        `#!python u{'hello': 1, 'hi': 2}` -> `#!python u{'hi': 2, 'hello': 1}` (reversed)
+        `#!py u{'hello': 1, 'hi': 2}` -> `#!py u{'hi': 2, 'hello': 1}` (reversed)
 
 !!! warning
-    `#!python reverse()` edits UDict. If you don't want to reverse UDict use [`#!python reversed()`](#reversed-udictkt-vt-cdv) method instead.
+    `#!py reverse()` edits UDict. If you don't want to reverse UDict use [`#!py reversed()`](#reversed-udictkt-vt-cdv) method instead.
 
 !!! example
-    ```python
+    ```py
     d.reverse()
     print(d) # prints reversed UDict
     ```
@@ -149,19 +149,19 @@ Reverses UDict and returns it. (1)
 Returns reversed UDict
 
 !!! example
-    ```python
+    ```py
     print(d.reversed())
     ```
 
-!!! tip "Get reversed UDict with inbuilt `#!python reversed()` and `#!python ~` operator"
-    You can get reversed UDict with inbuilt `#!python reversed()` and with invert operator (`~`).
+!!! tip "Get reversed UDict with inbuilt `#!py reversed()` and `#!py ~` operator"
+    You can get reversed UDict with inbuilt `#!py reversed()` and with invert operator (`~`).
     !!! example
         ```
         print(~d)
         print(reversed(d))
         print(d.reversed() == reversed(d)) # True
         ```
-    [Read more about `#!python reversed()` and `#!python ~` support in UDict](#magic-methods)
+    [Read more about `#!py reversed()` and `#!py ~` support in UDict](#__invert__-udictkt-vt-cdv)
 
 ## sort() -> UDict[KT, VT, CDV]
 
@@ -171,13 +171,13 @@ Sorts UDict and returns it. (1)
 1.  !!! question "How UDict is being sorting?"
 
         Just are being sorting items by keys.  
-        `#!python u{'b': 1, 'a': 2}` -> `#!python u{'a': 2, 'b': 1}` (sorted)
+        `#!py u{'b': 1, 'a': 2}` -> `#!py u{'a': 2, 'b': 1}` (sorted)
 
 !!! warning
-    `#!python sort()` edits UDict. If you don't want to sort UDict use [`#!python sorted()`](#sorted-udictkt-vt-cdv) method instead.
+    `#!py sort()` edits UDict. If you don't want to sort UDict use [`#!py sorted()`](#sorted-udictkt-vt-cdv) method instead.
 
 !!! example
-    ```python
+    ```py
     print(d.sort())
     ```
 
@@ -186,13 +186,13 @@ Sorts UDict and returns it. (1)
 Returns sorted UDict
 
 !!! example
-    ```python
+    ```py
     print(d.sorted())
     ```
 
 ##  get()
 
-```python
+```py
 def get(*, key: KT) -> VT | CDV
 def get(*, key: KT, default: DV) -> VT | DV
 def get(*, index: int) -> VT | CDV
@@ -210,7 +210,7 @@ Arguments:
 UDict value's key to find.
 
 !!! example
-    ```python
+    ```py
     print(d.get(key='key')) # same that d['key']
     ```
 
@@ -222,11 +222,11 @@ UDict value's index to find
     Indexes are starting from 1. Index of first element of UDict is 1.
 
 !!! failure "`index` argument more than UDict length"
-    If you use `index` argument make sure that `index` are less than UDict length. Otherwise `#!python get()`
+    If you use `index` argument make sure that `index` are less than UDict length. Otherwise `#!py get()`
     will raise `IndexError`
 
 !!! example
-    ```python
+    ```py
     print(d.get(index=2)) # second value of UDict
     ```
 
@@ -235,10 +235,46 @@ UDict value's index to find
 UDict key's value to find
 
 !!! example
-    ```python
+    ```py
     print(d.get(value=1)) # if d = UDict{'hello': 1}, this will be 'hello'
     ```
 
+#### `default: DV`
+
+Default value, if the result was not found. If not provided, then `default` is `UDict.default` property.
+
+!!! example
+    ```py
+    d = UDict(hello=1, hi=2, default=-1)
+    print(d.get(key='hell')) # -1
+    print(d.get(key='hell', default=None)) # None
+    ```
+
+## is_empty() -> bool
+
+`#!py True` if `len(UDict) == 0` else `#!py False`
+
+!!! example
+    ```py
+        d = UDict(hello=1)
+        d2 = UDict()
+        print(d.is_empty()) # False
+        print(d2.is_empty()) # True
+    ```
+
+!!! tip "Convert UDict to `#!py bool`"
+    You can convert UDict to `#!py bool` or use UDict in `#!py if` statement. If `#!py UDict.is_empty() == True`
+    then `#!py bool(UDict)` is False and by contrast. Same in `#!py if` because of `#!py if x` is the equivalent
+    of `#!py if bool(x)`
+
+    !!! example
+        ```py
+        # d is from code above
+        print(bool(d)) # True
+        if d:
+            print("d is True") # d is True
+        ```
+
 ## Magic methods
 
 Currently, UDict supports all these magic methods:
@@ -254,12 +290,140 @@ First argument of function is key, second is value. Returns new value
 
 
 !!! example
-    ```python
+    ```py
     def f(k, v):
         return v * 2
     d = d(f) # multiply all values by 2
     ```
 
+### _\_neg__() -> UDict[KT, int | float, CDV]
+
+Does all values (if they support `-` operator) to they's opposite numbers.
+
+!!! example
+    ```py
+    d = UDict(hello=1, hi=-2)
+    print(-d) # u{'hello': -1, 'hi': 2}
+    ```
+
+### _\_invert__() -> UDict[KT, VT, CDV]
+
+The equivalent of [`#!py reversed()`](#reversed-udictkt-vt-cdv)
+
+!!! example
+    ```py
+    print(~d)
+    ```
+
+### _\_reversed__() -> UDict[KT, VT, CDV]
+
+The equivalent of [`#!py reversed()`](#reversed-udictkt-vt-cdv)
+
+!!! example
+    ```py
+    print(reversed(d))
+    ```
+
+### _\_getitem__(key: KT | int | slice) -> UDict[KT, VT, DV] | VT
+
+Returns value for one key, or UDict for multiply keys provided with slice.
+
+Arguments:
+#### `key: KT | int | slice`
+
+Value's key or index to get or values's indexes slice to get.
+
+!!! example
+    ```py
+    print(d['hello'])
+    ```
+
+!!! tip "Using indexes and slices"
+    You can use indexes and slices in `#!py __getitem__()`.
+
+    !!! warning "Indexes starting at 1."
+
+    !!! failure
+        Keep in mind that indexes are using after the keys with the given value were not found.
+        !!! example
+            If you have `#!py 1` key, `d[1]` syntax will use `#!py 1` how key, not index. If you want to use index in
+            all ways, use [`#!py get()`](#get) instead.
+
+    !!! example
+        ```py
+        d = UDict(hello=1, hi=9)
+        print(d[2]) # 9
+        ```
+
+    Slices can be used only with indexes. If slice is provided, method will return part of UDict from `start` index to
+    `end` index with `step`.
+
+    !!! example
+        ```py
+        d = UDict(hello=1, hi=3, world=9, ufpy=2)
+        print(d[:3]) # u{'hello': 1, 'hi': 3, 'world': 9}
+        print(d[2:3]) # u{'hi': 3, 'world': 9}
+        print(d[:3:2]) # u{'hello': 1, 'world': 9}
+        ```
+
+### _\_setitem__(key: KT | int | slice, value: VT | list[VT] | tuple[VT])
+
+Sets value or values to given key or keys.
+
+#### `key: KT | int | slice`
+
+Value's key or keys to set. This argument is the same with [`key` argument in `#!py __getitem__()` method](#key-kt-int-slice)
+
+#### `value: VT | list[VT] | tuple[VT]`
+
+Value or values to set.
+
+!!! example
+    ```py
+    d = UDict(hello=2, hi=1)
+    d[2] = 'hello'
+    print(d['hi']) # 'hello'
+    d[:] = 'hello', 'world'
+    print(d) # u{'hello': 'hello', 'hi': 'world'}
+    ```
+
+### _\_delitem__(key: KT | int | slice)
+
+Deletes items with given key or keys
+
+#### `key: KT | int | slice`
+
+Item 's key or keys to delete. This argument is the same with [`key` argument in `#!py __getitem__()` method](#key-kt-int-slice)
+
+### _\_len__() -> int
+
+Returns length of UDict
+
+!!! example
+    d = UDict(hello=1, hi=2)
+    print(len(d)) # 2
+
+### _\_iter__() -> Iterator[tuple[KT, VT]]
+
+Iterate UDict. The equivalent of `#!py items.__iter__()`.
+
+!!! example
+    ```py
+    for k, v in d:
+        print(f"Key: {k}\nValue: {v}") # Prints all keys and its values.
+    ```
+
+### _\_bool__() -> bool
+
+Returns that UDict is not empty. The equivalent of `#!py not is_empty()`
+
+!!! example
+    ```py
+    print(bool(d))
+    if d:
+        print("D is not empty!")
+    ```
+
 *[KT]: Key type
 *[VT]: Value type
 *[CDV]: Class default value