align rem and quot methodologies with Clojure (#849)

Hi,

could you please consider patch to align the `rem` and `quot` results
with those of Clojure. It fixes #848.

This supersedes the decision to have `quot` use floored division
implemented #823.

This is to opt for full compatibility with Clojure, rather than using
numerically different but optimised python implementations. Users can
decide to use the corresponding python operators if they would like to
do otherwise.

I've also added some new test cases to cover additional results.

Thanks

---------

Co-authored-by: ikappaki <[email protected]>

Author: ikappaki

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
  * Cause exceptions arising from compilation issues during macroexpansion will no longer be nested for each level of macroexpansion (#852)
  * Support for optional metadata argument in `defmulti` (#857)
+ * Aligned `rem` and `quot` methodologies with corresponding Clojure fns (#848)
 
 ### Fixed
  * Fix a bug where `basilisp.lang.compiler.exception.CompilerException` would nearly always suppress line information in it's `data` map (#845)

docs/differencesfromclojure.rst

@@ -133,13 +133,6 @@ Libs
 
 Support for Clojure libs is `planned <https://github.com/basilisp-lang/basilisp/issues/668>`_\.
 
-.. _core_lib_differences:
-
-core
-----------
-
-The :lpy:fn:`quot` function utilizes the ``\\`` operator, resulting in a floor operation towards negative infinity. In contrast, Clojure rounds the result towards zero. Consequently, negative results exhibit a difference of -1 between Basilisp and Clojure.
-
 .. _refs_and_transactions_differences:
 
 Refs and Transactions

docs/pyinterop.rst

@@ -244,4 +244,19 @@ Type hints may be applied to :lpy:form:`def` names, function arguments and retur
 
    Due to the complexity of supporting multi-arity functions in Python, only return annotations are preserved on the arity dispatch function.
    Return annotations are combined as by ``typing.Union``, so ``typing.Union[str, str] == str``.
-   The annotations for individual arity arguments are preserved in their compiled form, but they are challenging to access programmatically.
+   The annotations for individual arity arguments are preserved in their compiled form, but they are challenging to access programmatically.
+
+.. _arithmeticdivision
+
+Arithmetic division
+-------------------
+
+:lpy:fn:`basilisp.core/quot`, :lpy:fn:`basilisp.core/rem` and :lpy:fn:`basilisp.core/mod` functions.
+
+The Python native quotient ``//`` and modulo ``%`` operators may yield different results compared to their Java counterpart's long division and modulo operators. The discrepancy arises from Python's choice of floored division (`src <http://python-history.blogspot.com/2010/08/why-pythons-integer-division-floors.html>`_, `archived <https://web.archive.org/web/20100827160949/http://python-history.blogspot.com/2010/08/why-pythons-integer-division-floors.html>`_) while Java employs truncated division for its calculations (refer to the to the `Wikipedia Modulo page <https://en.wikipedia.org/wiki/Modulo>`_ for a a comprehensive list of available division formulae).
+
+In Clojure, the ``clojure.core/quot`` function utilizes Java's long division operator, and the ``%`` operator is employed in defining the ``clojure.core/rem`` function. The ``clojure.core/mod`` function is subsequently established through floored division based on the latter.
+
+Basilisp has chosen to adopt the same mathematical formulae as Clojure for these three functions, rather than using the Python's built in operators under all cases. This approach offers the advantage of enhanced cross-platform compatibility without requiring modification, and ensures compatibility with examples in  `ClojureDocs <https://clojuredocs.org/>`_.
+
+Users still have the option to use the native `operator/floordiv <https://docs.python.org/3/library/operator.html#operator.floordiv>`_, i.e. Python's ``//``  operator, if they prefer so.

src/basilisp/core.lpy

@@ -1089,21 +1089,25 @@
   (python/abs x))
 
 (defn ^:inline mod
-  "Returns the modulo of ``num`` and ``div``\\."
+  "Returns the modulo of ``num`` and ``div``\\.
+
+  It uses floored division for calculating the quotient."
   [num div]
   (operator/mod num div))
 
 (defn ^:inline quot
   "Returns the quotient of ``num`` and ``div``\\.
 
-  The result is rounded towards negative infinity."
+  The division result is truncated."
   [num div]
-  (operator/floordiv num div))
+  (int (/ num div)))
+
+(defn ^:inline rem
+  "Returns the remainder of ``num`` and ``div``\\.
 
-(defn rem
-  "Returns the remainder of ``num`` and ``div``\\."
+  It uses truncated division for calculating the quotient."
   [num div]
-  (math/remainder num div))
+  (- num (* div (int (/ num div)))))
 
 (defn ^:inline inc
   "Increment the argument by 1."

tests/basilisp/core_test.py

@@ -391,6 +391,18 @@ def test_division(self):
             (4, 10, 6),
             (0, 10, 10),
             (0, 10, -1),
+            (1, 5, 2),
+            (1, -5, 2),
+            (-1, 5, -2),
+            (-1, -5, -2),
+            (2, 5, 3),
+            (1, -5, 3),
+            (-1, 5, -3),
+            (-2, -5, -3),
+            (1, 5, 4),
+            (3, -5, 4),
+            (-3, 5, -4),
+            (-1, -5, -4),
             (3, -21, 4),
             (3, -2, 5),
             (2, -10, 3),
@@ -407,16 +419,28 @@ def test_mod(self, result, x, y):
         "result,x,y",
         [
             (0, 1, 2),
+            (2, 5, 2),
+            (-2, -5, 2),
+            (-2, 5, -2),
+            (2, -5, -2),
+            (1, 5, 3),
+            (-1, -5, 3),
+            (-1, 5, -3),
+            (1, -5, -3),
+            (1, 5, 4),
+            (-1, -5, 4),
+            (-1, 5, -4),
+            (1, -5, -4),
             (1, 2, 2),
             (1, 3, 2),
             (2, 4, 2),
             (3, 10, 3),
             (3, 11, 3),
             (4, 12, 3),
             (1.0, 5.9, 3),
-            (-2.0, -5.9, 3),
-            (-4, -10, 3),
-            (-4, 10, -3),
+            (-1.0, -5.9, 3),
+            (-3, -10, 3),
+            (-3, 10, -3),
             (3, 10, 3),
             (
                 44879032948094820938438942938402938402984209842098984209449032094205874758758475837584759347,
@@ -429,7 +453,27 @@ def test_quot(self, result, x, y):
         assert result == core.quot(x, y)
 
     @pytest.mark.parametrize(
-        "result,x,y", [(1, 10, 9), (0, 2, 2), (-1, -10, 3), (-1, -21, 4)]
+        "result,x,y",
+        [
+            (1, 10, 9),
+            (0, 2, 2),
+            (1, 5, 2),
+            (-1, -5, 2),
+            (1, 5, -2),
+            (-1, -5, -2),
+            (2, 5, 3),
+            (-2, -5, 3),
+            (2, 5, -3),
+            (-2, -5, -3),
+            (1, 5, 4),
+            (-1, -5, 4),
+            (1, 5, -4),
+            (-1, -5, -4),
+            (1, 3, 2),
+            (-1, -3, 2),
+            (-1, -10, 3),
+            (-1, -21, 4),
+        ],
     )
     def test_rem(self, result, x, y):
         assert result == core.rem(x, y)