[decimal] Rename floor_divide to truncate_divide to avoid ambiguity (#52)

This pull request involves renaming the `floor_divide` function and all
related references to `truncate_divide` across multiple files. The
changes ensure consistency in the naming convention and update the logic
accordingly.

### Renaming and Updating Functions:
* `benches/decimal/bench.mojo`: Renamed `bench_floor_divide` to
`bench_truncate_divide` in the import statements and function calls.
* `benches/decimal/bench_truncate_divide.mojo`: Renamed from
`bench_floor_divide.mojo` and updated all instances of
`run_benchmark_floor_divide` to `run_benchmark_truncate_divide`.
* `src/decimojo/__init__.mojo`: Updated import statement from
`floor_divide` to `truncate_divide`.
* `src/decimojo/decimal/arithmetics.mojo`: Renamed `floor_divide`
function to `truncate_divide` and updated the corresponding logic in the
`modulo` function.

### Updating `Decimal` Struct:
* `src/decimojo/decimal/decimal.mojo`: Updated all instances of
`floor_divide` to `truncate_divide` in the `__floordiv__`, `__mod__`,
`__rfloordiv__`, `__rmod__`, `__ifloordiv__`, and `__imod__` methods.
Added docstrings to reflect the changes.

Author: forfudan

benches/decimal/bench.mojo

@@ -2,7 +2,7 @@ from bench_add import main as bench_add
 from bench_subtract import main as bench_subtract
 from bench_multiply import main as bench_multiply
 from bench_divide import main as bench_divide
-from bench_floor_divide import main as bench_floor_divide
+from bench_truncate_divide import main as bench_truncate_divide
 from bench_modulo import main as bench_modulo
 from bench_sqrt import main as bench_sqrt
 from bench_from_float import main as bench_from_float
@@ -23,7 +23,7 @@ fn main() raises:
     bench_subtract()
     bench_multiply()
     bench_divide()
-    bench_floor_divide()
+    bench_truncate_divide()
     bench_modulo()
     bench_sqrt()
     bench_from_float()

benches/decimal/bench_floor_divide.mojo …nches/decimal/bench_truncate_divide.mojobenches/decimal/bench_floor_divide.mojo renamed to benches/decimal/bench_truncate_divide.mojo benches/decimal/bench_floor_divide.mojo renamed to benches/decimal/bench_truncate_divide.mojo

@@ -28,7 +28,7 @@ fn open_log_file() raises -> PythonObject:
 
     # Generate a timestamp for the filename
     var timestamp = String(datetime.datetime.now().isoformat())
-    var log_filename = log_dir + "/benchmark_floor_divide_" + timestamp + ".log"
+    var log_filename = log_dir + "/benchmark_truncate_divide_" + timestamp + ".log"
 
     print("Saving benchmark results to:", log_filename)
     return python.open(log_filename, "w")
@@ -47,7 +47,7 @@ fn log_print(msg: String, log_file: PythonObject) raises:
     log_file.flush()  # Ensure the message is written immediately
 
 
-fn run_benchmark_floor_divide(
+fn run_benchmark_truncate_divide(
     name: String,
     dividend: String,
     divisor: String,
@@ -168,7 +168,7 @@ fn main() raises:
     )
 
     # Case 1: Basic integer floor division with no remainder
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Integer division, no remainder",
         "10",
         "2",
@@ -178,7 +178,7 @@ fn main() raises:
     )
 
     # Case 2: Basic integer floor division with remainder
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Integer division, with remainder",
         "10",
         "3",
@@ -188,7 +188,7 @@ fn main() raises:
     )
 
     # Case 3: Division with decimal values
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Decimal division",
         "10.5",
         "2.5",
@@ -198,7 +198,7 @@ fn main() raises:
     )
 
     # Case 4: Division resulting in a decimal value
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Division resulting in integer",
         "5",
         "2",
@@ -208,7 +208,7 @@ fn main() raises:
     )
 
     # Case 5: Division with different decimal places
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Different decimal places",
         "10.75",
         "1.5",
@@ -218,7 +218,7 @@ fn main() raises:
     )
 
     # Case 6: Negative dividend, positive divisor
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Negative dividend, positive divisor",
         "-10",
         "3",
@@ -228,7 +228,7 @@ fn main() raises:
     )
 
     # Case 7: Positive dividend, negative divisor
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Positive dividend, negative divisor",
         "10",
         "-3",
@@ -238,7 +238,7 @@ fn main() raises:
     )
 
     # Case 8: Negative dividend, negative divisor
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Negative dividend, negative divisor",
         "-10",
         "-3",
@@ -248,7 +248,7 @@ fn main() raises:
     )
 
     # Case 9: Decimal values, negative dividend, positive divisor
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Decimal, negative dividend, positive divisor",
         "-10.5",
         "3.5",
@@ -258,7 +258,7 @@ fn main() raises:
     )
 
     # Case 10: Division by 1
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Division by 1",
         "10",
         "1",
@@ -268,7 +268,7 @@ fn main() raises:
     )
 
     # Case 11: Zero dividend
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Zero dividend",
         "0",
         "5",
@@ -278,7 +278,7 @@ fn main() raises:
     )
 
     # Case 12: Division by a decimal < 1
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Division by decimal < 1",
         "10",
         "0.5",
@@ -288,7 +288,7 @@ fn main() raises:
     )
 
     # Case 13: Division resulting in a negative zero
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Division resulting in zero",
         "0",
         "-5",
@@ -298,7 +298,7 @@ fn main() raises:
     )
 
     # Case 14: Large number division
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Large number division",
         "1000000000",
         "7",
@@ -308,7 +308,7 @@ fn main() raises:
     )
 
     # Case 15: Small number division
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Small number division",
         "0.0000001",
         "0.0000002",
@@ -318,7 +318,7 @@ fn main() raises:
     )
 
     # Case 16: Very large dividend and divisor
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Large dividend and divisor",
         "123456789012345",
         "987654321",
@@ -328,7 +328,7 @@ fn main() raises:
     )
 
     # Case 17: High precision dividend
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "High precision dividend",
         "3.14159265358979323846",
         "1.5",
@@ -338,7 +338,7 @@ fn main() raises:
     )
 
     # Case 18: Very close values
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Very close values",
         "1.0000001",
         "1",
@@ -348,7 +348,7 @@ fn main() raises:
     )
 
     # Case 19: Power of 10 values
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Power of 10 values",
         "10000",
         "100",
@@ -358,7 +358,7 @@ fn main() raises:
     )
 
     # Case 20: Edge values not quite reaching the next integer
-    run_benchmark_floor_divide(
+    run_benchmark_truncate_divide(
         "Edge values",
         "9.9999999",
         "2",

src/decimojo/__init__.mojo

@@ -38,7 +38,7 @@ from .decimal.arithmetics import (
     negative,
     multiply,
     divide,
-    floor_divide,
+    truncate_divide,
     modulo,
 )
 

src/decimojo/decimal/arithmetics.mojo

@@ -1138,8 +1138,8 @@ fn divide(x1: Decimal, x2: Decimal) raises -> Decimal:
             return Decimal(low, mid, high, scale_of_truncated_quot, is_negative)
 
 
-fn floor_divide(x1: Decimal, x2: Decimal) raises -> Decimal:
-    """Returns the integral part of the true quotient (truncating towards zero).
+fn truncate_divide(x1: Decimal, x2: Decimal) raises -> Decimal:
+    """Returns the integral part of the quotient (truncating towards zero).
     The following identity always holds: x_1 == (x_1 // x_2) * x_2 + x_1 % x_2.
 
     Args:
@@ -1167,6 +1167,6 @@ fn modulo(x1: Decimal, x2: Decimal) raises -> Decimal:
         A new Decimal containing the remainder of x1 / x2.
     """
     try:
-        return x1 - (floor_divide(x1, x2) * x2)
+        return x1 - (truncate_divide(x1, x2) * x2)
     except e:
         raise Error("Error in `modulo()`: ", e)

src/decimojo/decimal/decimal.mojo

@@ -1190,18 +1190,24 @@ struct Decimal(
 
     @always_inline
     fn __floordiv__(self, other: Self) raises -> Self:
-        return decimojo.decimal.arithmetics.floor_divide(self, other)
+        """Performs truncate division with // operator."""
+        return decimojo.decimal.arithmetics.truncate_divide(self, other)
 
     @always_inline
     fn __floordiv__(self, other: Int) raises -> Self:
-        return decimojo.decimal.arithmetics.floor_divide(self, Decimal(other))
+        """Performs truncate division with // operator."""
+        return decimojo.decimal.arithmetics.truncate_divide(
+            self, Decimal(other)
+        )
 
     @always_inline
     fn __mod__(self, other: Self) raises -> Self:
+        """Performs truncate modulo."""
         return decimojo.decimal.arithmetics.modulo(self, other)
 
     @always_inline
     fn __mod__(self, other: Int) raises -> Self:
+        """Performs truncate modulo."""
         return decimojo.decimal.arithmetics.modulo(self, Decimal(other))
 
     @always_inline
@@ -1237,10 +1243,14 @@ struct Decimal(
 
     @always_inline
     fn __rfloordiv__(self, other: Int) raises -> Self:
-        return decimojo.decimal.arithmetics.floor_divide(Decimal(other), self)
+        """Performs truncate division with // operator."""
+        return decimojo.decimal.arithmetics.truncate_divide(
+            Decimal(other), self
+        )
 
     @always_inline
     fn __rmod__(self, other: Int) raises -> Self:
+        """Performs truncate modulo."""
         return decimojo.decimal.arithmetics.modulo(Decimal(other), self)
 
     # ===------------------------------------------------------------------=== #
@@ -1284,11 +1294,20 @@ struct Decimal(
 
     @always_inline
     fn __ifloordiv__(mut self, other: Self) raises:
-        self = decimojo.decimal.arithmetics.floor_divide(self, other)
+        """Performs truncate division with // operator."""
+        self = decimojo.decimal.arithmetics.truncate_divide(self, other)
 
     @always_inline
     fn __ifloordiv__(mut self, other: Int) raises:
-        self = decimojo.decimal.arithmetics.floor_divide(self, Decimal(other))
+        """Performs truncate division with // operator."""
+        self = decimojo.decimal.arithmetics.truncate_divide(
+            self, Decimal(other)
+        )
+
+    @always_inline
+    fn __imod__(mut self, other: Self) raises:
+        """Performs truncate modulo."""
+        self = decimojo.decimal.arithmetics.modulo(self, other)
 
     # ===------------------------------------------------------------------=== #
     # Basic binary comparison operation dunders