Documented all methods and functions.

bitutilities.py

@@ -36,17 +36,38 @@ class BasicRegister:
         )
 
     def reverse(self):
+        """
+        Performs a logical negation on the register.
+        """
         self.memory = deque([not value for value in self.memory])
 
-    def left_shift(self, digit_to_fill: bool = False, steps_shifted: int = 1) -> deque[bool]:
-        self.memory.extend([digit_to_fill] * steps_shifted)
-        shifted_radices: deque[bool] = deque([self.memory.popleft() for _i in range(steps_shifted)])
-        return shifted_radices
+    def left_shift(self, shift_in_value: bool = False, bits_shifted: int = 1) -> deque[bool]:
+        """
+        Shifts the register to the left by a specified number of steps
 
-    def right_shift(self, digit_to_fill: bool = False, steps_shifted: int = 1) -> deque[bool]:
-        self.memory.extendleft([digit_to_fill] * steps_shifted)
-        shifted_radices: deque[bool] = deque([self.memory.pop() for _i in range(steps_shifted)])
-        return shifted_radices
+        :param bool shift_in_value: The value that shifts inside the freed space.
+        :param int bits_shifted: The number of bits by which the register is shifted.
+
+        :return: The bits shifted outside the register.
+        :rtype: deque[bool]
+        """
+        self.memory.extend([shift_in_value] * bits_shifted)
+        shifted_bits: deque[bool] = deque([self.memory.popleft() for _i in range(bits_shifted)])
+        return shifted_bits
+
+    def right_shift(self, shift_in_value: bool = False, bits_shifted: int = 1) -> deque[bool]:
+        """
+        Shifts the register to the right by a specified number of steps
+
+        :param bool shift_in_value: The value that shifts inside the freed space.
+        :param int bits_shifted: The number of bits by which the register is shifted.
+
+        :return: The bits shifted outside the register.
+        :rtype: deque[bool]
+        """
+        self.memory.extendleft([shift_in_value] * bits_shifted)
+        shifted_bits: deque[bool] = deque([self.memory.pop() for _i in range(bits_shifted)])
+        return shifted_bits
 
 
 def get_memory(variable_name: str) -> list[bool]:
@@ -68,6 +89,15 @@ def get_memory(variable_name: str) -> list[bool]:
 
 
 def binary_sum_with_carry(first_term: BasicRegister, second_term: BasicRegister) -> tuple[BasicRegister, int]:
+    """
+    Sums two registers' values and keeps the carry-out.
+
+    :param BasicRegister first_term: First register.
+    :param BasicRegister second_term: Second register.
+
+    :return: Register containing the sum and the carry-out bit.
+    :rtype: tuple[BasicRegister, int]
+    """
     result_term = BasicRegister([False] * len(first_term))
 
     carry = False
@@ -85,39 +115,70 @@ def binary_sum_with_carry(first_term: BasicRegister, second_term: BasicRegister)
 
 def binary_sum(first_term: BasicRegister, second_term: BasicRegister) -> BasicRegister:
     """
-    Sums two registers' values.
+    Sums two terms containing binary numbers.
 
-    :param BasicRegister first_term: First register.
-    :param BasicRegister second_term: Second register.
+    :param BasicRegister first_term: First register to add.
+    :param BasicRegister second_term: Second register to add.
 
-    :return: Register containing the sum or the tuple containing the register and carried radix.
-    :rtype: BasicRegister | tuple[BasicRegister, int]
+    :return: Register containing the sum.
+    :rtype: BasicRegister
     """
     return binary_sum_with_carry(first_term, second_term)[0]
 
 
-def binary_subtraction(first_term: BasicRegister, second_term: BasicRegister) -> BasicRegister:
-    second_term.reverse()
+def binary_subtraction(minuend: BasicRegister, subtrahend: BasicRegister) -> BasicRegister:
+    """
+    Subtracts the second term from the first in binary using ones' complement.
 
-    result: BasicRegister
+    :param BasicRegister minuend: Register to subtract from.
+    :param BasicRegister subtrahend: Register to subtract by.
+
+    :return: Register containing the difference.
+    :rtype: BasicRegister
+    """
+    subtrahend.reverse()
+
+    difference: BasicRegister
     final_carry: bool
-    result, final_carry = binary_sum_with_carry(first_term, second_term)
+    difference, final_carry = binary_sum_with_carry(minuend, subtrahend)
 
     if final_carry:
-        return binary_sum(result, BasicRegister([False] * (len(result) - 1) + [True]))
+        return binary_sum(difference, BasicRegister([False] * (len(difference) - 1) + [True]))
     else:
-        result.reverse()
-        return result
+        difference.reverse()
+        return difference
 
 
-def align_registers(first_register: BasicRegister, second_register: BasicRegister) \
-        -> tuple[BasicRegister, BasicRegister]:
-    first_size = len(first_register)
-    second_size = len(second_register)
+# def align_registers(first_register: BasicRegister, second_register: BasicRegister) \
+#         -> tuple[BasicRegister, BasicRegister]:
+#     """
+#     Aligns two registers by the length of the bigger one.
+#
+#     :param BasicRegister first_register:
+#     :param BasicRegister second_register:
+#
+#     :return:
+#     :rtype: tuple[BasicRegister, BasicRegister]
+#     """
+#     first_size = len(first_register)
+#     second_size = len(second_register)
+#
+#     required_size = max(first_size, second_size)
+#
+#     if first_size != second_size:
+#         return first_register.adjusted_by_size(required_size), second_register.adjusted_by_size(required_size)
+#     else:
+#         return first_register, second_register
 
-    required_size = max(first_size, second_size)
 
-    if first_size != second_size:
-        return first_register.adjusted_by_size(required_size), second_register.adjusted_by_size(required_size)
-    else:
-        return first_register, second_register
+def align_registers(*args: BasicRegister) -> tuple[BasicRegister, ...]:
+    """
+    Aligns registers by the length of the bigger one.
+
+    :param args: Basic registers to align.
+
+    :return: Aligned registers.
+    :rtype: tuple[BasicRegister, ...]
+    """
+    required_size: int = max(map(len, args))
+    return tuple(reg.adjusted_by_size(required_size) for reg in args)