Implement 3-way comparator (#609)

* Implement 3-way comparator

* c o v e r a g e

* Some new stuff

* Fix the tests

* Test it

* Do that thing

* Don't forget the negation

* Dead

Author: chrisrink10

src/basilisp/core.lpy

@@ -1061,8 +1061,37 @@
   [frac]
   (.-denominator frac))
 
+(defn compare
+  "Return either -1, 0, or 1 to indicate the relationship between x and y.
+
+  This is a 3-way comparator commonly used in Java-derived systems. Python does not
+  typically use 3-way comparators, so this function convert's Python's `__lt__` and
+  `__gt__` method returns into one of the 3-way comparator return values.
+
+  Comparisons are generally only valid between homogeneous objects, with the exception
+  of numbers which can be compared regardless of type. Most scalar value types
+  (including nil, booleans, numbers, strings, keywords, and symbols) are comparable.
+  nil compares less than all values except itself. NaN compares equal to all numbers,
+  including itself. Strings are compared lexicographically. Symbols and keywords are
+  sorted first on their namespace, if they have one, and then on their name. Symbols
+  and keywords with namespaces always sort ahead of those without. Symbols cannot be
+  compared to keywords.
+
+  Of the built in collection types, only vectors can be compared. Vectors are compared
+  first by their length and then element-wise.
+
+  Other collections such as maps, sequences, and sets cannot be compared.
+
+  Python objects supporting `__lt__` and `__gt__` can generally be compared."
+  [x y]
+  (basilisp.lang.runtime/compare x y))
+
 (defn sort
-  "Return a sorted sequence of the elements from coll."
+  "Return a sorted sequence of the elements from coll.
+
+  Unlike in Clojure, this function does not use `compare` directly. Instead, the
+  heuristics that `compare` uses to produce three-way comparator return values
+  are used to guide sorting."
   ([coll]
    (basilisp.lang.runtime/sort coll))
   ([cmp coll]

src/basilisp/lang/keyword.py

@@ -1,4 +1,5 @@
 import threading
+from functools import total_ordering
 from typing import Iterable, Optional
 
 from basilisp.lang import map as lmap
@@ -8,6 +9,7 @@
 _INTERN: IPersistentMap[int, "Keyword"] = lmap.PersistentMap.empty()
 
 
+@total_ordering
 class Keyword(ILispObject):
     __slots__ = ("_name", "_ns", "_hash")
 
@@ -38,6 +40,19 @@ def __eq__(self, other):
     def __hash__(self):
         return self._hash
 
+    def __lt__(self, other):
+        if other is None:  # pragma: no cover
+            return False
+        if not isinstance(other, Keyword):
+            return NotImplemented
+        if self._ns is None and other._ns is None:
+            return self._name < other._name
+        if self._ns is None:
+            return True
+        if other._ns is None:
+            return False
+        return self._ns < other._ns or self._name < other._name
+
     def __call__(self, m: IAssociative, default=None):
         try:
             return m.val_at(self, default)

src/basilisp/lang/runtime.py

@@ -1,4 +1,5 @@
 import contextlib
+import decimal
 import functools
 import importlib
 import inspect
@@ -1249,6 +1250,55 @@ def quotient(num, div) -> LispNumber:
     return math.trunc(num / div)
 
 
+@functools.singledispatch
+def compare(x, y) -> int:
+    """Return either -1, 0, or 1 to indicate the relationship between x and y.
+
+    This is a 3-way comparator commonly used in Java-derived systems. Python does not
+    typically use 3-way comparators, so this function convert's Python's `__lt__` and
+    `__gt__` method returns into one of the 3-way comparator return values."""
+    if y is None:
+        assert x is not None, "x cannot be nil"
+        return 1
+    return (x > y) - (x < y)
+
+
+@compare.register(type(None))
+def _compare_nil(_: None, y) -> int:
+    # nil is less than all values, except itself.
+    return 0 if y is None else -1
+
+
+@compare.register(decimal.Decimal)
+def _compare_decimal(x: decimal.Decimal, y) -> int:
+    # Decimal instances will not compare with float("nan"), so we need a special case
+    if isinstance(y, float):
+        return -compare(y, x)  # pylint: disable=arguments-out-of-order
+    return (x > y) - (x < y)
+
+
+@compare.register(float)
+def _compare_float(x, y) -> int:
+    if y is None:
+        return 1
+    if math.isnan(x):
+        return 0
+    return (x > y) - (x < y)
+
+
+@compare.register(IPersistentSet)
+def _compare_sets(x: IPersistentSet, y) -> int:
+    # Sets are not comparable (because there is no total ordering between sets).
+    # However, in Python comparison is done using __lt__ and __gt__, which AbstractSet
+    # inconveniently also uses as part of it's API for comparing sets with subset and
+    # superset relationships. To "break" that, we just override the comparison method.
+    # One consequence of this is that it may be possible to sort a collection of sets,
+    # since `compare` isn't actually consulted in sorting.
+    raise TypeError(
+        f"cannot compare instances of '{type(x).__name__}' and '{type(y).__name__}'"
+    )
+
+
 def sort(coll, f=None) -> Optional[ISeq]:
     """Return a sorted sequence of the elements in coll. If a comparator
     function f is provided, compare elements in coll using f."""

src/basilisp/lang/symbol.py

@@ -1,10 +1,12 @@
+from functools import total_ordering
 from typing import Optional
 
 from basilisp.lang.interfaces import ILispObject, IPersistentMap, IWithMeta
 from basilisp.lang.obj import lrepr
 from basilisp.lang.util import munge
 
 
+@total_ordering
 class Symbol(ILispObject, IWithMeta):
     __slots__ = ("_name", "_ns", "_meta", "_hash")
 
@@ -56,6 +58,19 @@ def __eq__(self, other):
     def __hash__(self):
         return self._hash
 
+    def __lt__(self, other):
+        if other is None:  # pragma: no cover
+            return False
+        if not isinstance(other, Symbol):
+            return NotImplemented
+        if self._ns is None and other._ns is None:
+            return self._name < other._name
+        if self._ns is None:
+            return True
+        if other._ns is None:
+            return False
+        return self._ns < other._ns or self._name < other._name
+
 
 def symbol(name: str, ns: Optional[str] = None, meta=None) -> Symbol:
     """Create a new symbol."""

src/basilisp/lang/vector.py

@@ -1,3 +1,4 @@
+from functools import total_ordering
 from typing import Iterable, Optional, Sequence, TypeVar, Union
 
 from pyrsistent import PVector, pvector  # noqa # pylint: disable=unused-import
@@ -74,6 +75,7 @@ def to_persistent(self) -> "PersistentVector[T]":
         return PersistentVector(self._inner.persistent())
 
 
+@total_ordering
 class PersistentVector(
     IPersistentVector[T], IEvolveableCollection[TransientVector], ILispObject, IWithMeta
 ):
@@ -116,6 +118,15 @@ def __iter__(self):
     def __len__(self):
         return len(self._inner)
 
+    def __lt__(self, other):
+        if other is None:  # pragma: no cover
+            return False
+        if not isinstance(other, PersistentVector):
+            return NotImplemented
+        if len(self) != len(other):
+            return len(self) < len(other)
+        return any(x < y for x, y in zip(self, other))
+
     def _lrepr(self, **kwargs) -> str:
         return _seq_lrepr(self._inner, "[", "]", meta=self._meta, **kwargs)
 

tests/basilisp/test_core_fns.lpy

@@ -75,6 +75,156 @@
           (is (= v1 v2))
           (is (= {:tag vector} (meta v2))))))))
 
+(deftest compare-test
+  (testing "nil"
+    (are [res x y] (= res (compare x y))
+      0  nil nil
+      -1 nil "a"
+      1  "a" nil))
+
+  (testing "boolean"
+    (are [res x y] (= res (compare x y))
+      0  true  true
+      0  false false
+      -1 false true
+      1  true  false))
+
+  (testing "numbers"
+    (are [res x y] (= res (compare x y))
+      1  ##NaN nil
+      -1 nil   ##NaN
+
+      0 ##NaN ##NaN
+      0 ##NaN 1
+      0 ##NaN 3.14
+      0 ##NaN 22/7
+      0 ##NaN 3.07M
+      0 3.07M ##NaN
+      0 1     ##NaN
+      0 3.14  ##NaN
+      0 3.14  ##NaN
+      0 22/7  ##NaN
+
+      0 1    1
+      0 1    1.0
+      0 1    1M
+      0 2    10/5
+      0 1.0  1
+      0 1.0  1M
+      0 1.0  1.0
+      0 2.0  10/5
+      0 1M   1M
+      0 1M   1
+      0 1M   1.0
+      0 2M   10/5
+      0 10/5 2
+      0 10/5 2.0
+      0 10/5 2M
+      0 10/5 10/5
+
+      1 3     1
+      1 3     1.07
+      1 3     2/5
+      1 3     1.07M
+      1 3.33  1.07
+      1 3.33  1
+      1 3.33  2/5
+      1 3.33  1.07M
+      1 3.33M 1.07M
+      1 3.33M 1
+      1 3.33M 1.07
+      1 3.33M 10/5
+      1 10/5  1
+      1 10/5  1.0
+      1 10/5  1.07M
+      1 10/5  2/5
+
+      -1 1     3
+      -1 1.07  3
+      -1 2/5   3
+      -1 1.07M 3
+      -1 1.07  3.33
+      -1 1     3.33
+      -1 2/5   3.33
+      -1 1.07M 3.33
+      -1 1.07M 3.33M
+      -1 1     3.33M
+      -1 1.07  3.33M
+      -1 10/5  3.33M
+      -1 1     10/5
+      -1 1.07  10/5
+      -1 1.07M 10/5
+      -1 2/5   10/5))
+
+  (testing "strings"
+    (are [res x y] (= res (compare x y))
+      0  "a" "a"
+      -1 "a" "b"
+      1  "b" "a"))
+
+  (testing "keywords"
+    (are [res x y] (= res (compare x y))
+      0  :a :a
+      -1 :a :b
+      1  :b :a
+
+      1  :a/b :b
+      -1 :b   :a/b
+
+      -1 :a/b :a/c
+      -1 :a/b :b/b
+      0  :a/b :a/b
+      1  :a/c :a/b
+      1  :b/b :a/b))
+
+  (testing "symbols"
+    (are [res x y] (= res (compare x y))
+      0  'a 'a
+      -1 'a 'b
+      1  'b 'a
+
+      1  'a/b 'b
+      -1 'b   'a/b
+
+      -1 'a/b 'a/c
+      -1 'a/b 'b/b
+      0  'a/b 'a/b
+      1  'a/c 'a/b
+      1  'b/b 'a/b))
+
+  (testing "vectors"
+    (are [res x y] (= res (compare x y))
+      0  []  []
+      -1 []  [1]
+      1  [1] []
+
+      0  [0 1 2] [0 1 2]
+      -1 [0 1 2] [1 1 2]
+      1  [1 1 2] [0 1 2]))
+
+  (testing "un-comparables"
+    (are [x y] (thrown? python/TypeError (compare x y))
+      :a  'a
+      :a  "a"
+      'a  "a"
+      'a  :a
+      "a" 'a
+      "a" :a
+
+      [] '()
+
+      '()      '()
+      '(1 2 3) '(1 2 3)
+      '(1 2 3) '(4 5 6)
+
+      #{}      #{}
+      #{1 2 3} #{1 2 3}
+      #{1 2 3} #{4 5 6}
+
+      {}          {}
+      {:a 1 :b 2} {:a 1 :b 2}
+      {:a 1 :b 2} {:c 3 :d 4})))
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Collection Functions ;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;