Added == as an alias for = (#868)

Hi,

could you please consider patch to add `==` as an alias for `=`. Fixes
#859.

I've also updated the doc to describe the difference of int vs float
comparison in basilisp vs Clojure.

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
  * Added `basilisp.stacktrace` namespace (#721)
  * Added support for `*flush-on-newline*` to flush the `prn` and `println` output stream after the last newline (#865)
  * Added support for binding destructuring in `for` bindings (#774)
+ * Added `==` as an alias to `=` (#859)
 
 ### Changed
  * Cause exceptions arising from compilation issues during macroexpansion will no longer be nested for each level of macroexpansion (#852)

docs/differencesfromclojure.rst

@@ -32,6 +32,23 @@ Type Differences
 
   * Sorted sets, sorted maps, and array maps are not implemented (support is tracked in `#416 <https://github.com/basilisp-lang/basilisp/issues/416>`_).
 
+.. _arithmetic_comparison:
+
+Arithmetic Comparison
+---------------------
+
+Basilisp, in contrast to Clojure, does not distinguish between integer (``int``) and floating point (``float``) as `separate categories for equality comparison purposes <https://clojure.org/guides/equality>`_ where the ``=`` comparison between any ``int`` and ``float`` returns ``false``. Instead, it adopts Python's ``=`` comparison operator semantics, where the ``int`` is optimistically converted to a ``float`` before the comparison. However, beware that this conversion can lead to `certain caveats in comparison <https://stackoverflow.com/a/30100743>`_ where in rare cases seemingly exact ``int`` and ``float`` numbers may still compare to ``false`` due to limitations in floating point number representation.
+
+In Clojure, this optimistic equality comparison is performed by the ``==`` function. In Basilisp, ``==`` is aliased to behave the same as ``=``.
+
+.. note::
+
+   Basilisp's ``=`` will perform as expected when using Python `Decimal <https://docs.python.org/3/library/decimal.html>`__ typed :ref:`floating_point_numbers`.
+
+.. seealso::
+
+   Python's `floating point arithmetic <https://docs.python.org/3/tutorial/floatingpoint.html>`_ documentation
+
 .. _concurrent_programming:
 
 Concurrent Programming

docs/pyinterop.rst

@@ -246,7 +246,7 @@ Type hints may be applied to :lpy:form:`def` names, function arguments and retur
    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.
 
-.. _arithmeticdivision
+.. _arithmeticdivision:
 
 Arithmetic division
 -------------------

src/basilisp/core.lpy

@@ -815,7 +815,11 @@
   (operator/is_ x y))
 
 (defn =
-  "Return ``true`` if ``x`` and ``y`` are equal, otherwise ``false``\\."
+  "Return ``true`` if ``x`` and ``y`` are equal, otherwise ``false``\\.
+
+  Number equality follows Python's ``=`` semantics whereby \"a
+  comparison between numbers of different types behaves as though the
+  exact values of those numbers were being compared\"."
   ([_] true)
   ([x & args]
    (if (seq (rest args))
@@ -829,6 +833,11 @@
   [& args]
   (not (apply = args)))
 
+(defn ==
+  "Alias for lpy:fn:`=`."
+  [& args]
+  (apply = args))
+
 (defn >
   "Return ``true`` if arguments are monotonically decreasing, otherwise ``false``\\."
   ([_] true)

tests/basilisp/test_core_fns.lpy

@@ -2211,3 +2211,17 @@
         (.flush *out*)
         (is (= (bio-write expected os/linesep "ab" os/linesep "ab" " " 1 os/linesep)
                (.getvalue bio)))))))
+
+;;;;;;;;;;;;;;;;
+;; arithmetic ;;
+;;;;;;;;;;;;;;;;
+
+(deftest arithmetic-equality-test
+  (testing "int and float type equality"
+    (is (not= 1 1.00001))
+    (is (= 1 1.0000000000000000000000009)))
+
+  (testing "== is an alias of ="
+    (let [f 1.0000000000000000000000009]
+      (is (= 1 f))
+      (is (== 1 f)))))