sort handles incomparable values

CHANGELOG.md

@@ -682,6 +682,7 @@
 - [Ensure calls involving warnings remain instrumented][6067]
 - [One can define lazy atom fields][6151]
 - [Replace IOContexts with Execution Environment and generic Context][6171]
+- [Vector.sort handles incomparable types][5998]
 
 [3227]: https://github.com/enso-org/enso/pull/3227
 [3248]: https://github.com/enso-org/enso/pull/3248
@@ -787,6 +788,7 @@
 [6067]: https://github.com/enso-org/enso/pull/6067
 [6151]: https://github.com/enso-org/enso/pull/6151
 [6171]: https://github.com/enso-org/enso/pull/6171
+[5998]: https://github.com/enso-org/enso/pull/5998
 
 # Enso 2.0.0-alpha.18 (2021-10-12)
 

distribution/lib/Standard/Base/0.0.0-dev/src/Any.enso

@@ -481,11 +481,11 @@ type Any
 
 ## PRIVATE
    Checks if the comparators for the given objects are both of the same type. If so,
-   proceeds with the given action, and if not, throws `Type_Error`.
-assert_same_comparators : Any -> Any -> (Any -> Any) -> Any ! Type_Error
+   proceeds with the given action, and if not, throws `Incomparable_Values` error.
+assert_same_comparators : Any -> Any -> (Any -> Any) -> Any ! Incomparable_Values
 assert_same_comparators this that ~action =
     comp_this = Comparable.from this
     comp_that = Comparable.from that
     case Meta.is_same_object comp_this comp_that of
         True -> action
-        False -> Error.throw (Type_Error.Error (Meta.type_of comp_this) comp_that "comp_that")
+        False -> Error.throw (Incomparable_Values.Error this that)

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Array.enso

@@ -14,6 +14,7 @@ import project.Error.Error
 import project.Errors.Common.Incomparable_Values
 import project.Errors.Common.Not_Found
 import project.Errors.Common.Index_Out_Of_Bounds
+import project.Errors.Problem_Behavior.Problem_Behavior
 import project.Meta
 import project.Nothing.Nothing
 import project.Panic.Panic
@@ -160,13 +161,17 @@ type Array
        Arguments:
        - order: The order in which the array elements are sorted.
        - on: A projection from the element type to the value of that element
-         being sorted on.
+         being sorted on. If set to `Nothing` (the default),
+         identity function will be used.
        - by: A function that compares the result of applying `on` to two
-         elements, returning an Ordering to compare them.
+         elements, returning an an `Ordering` if the two elements are comparable
+         or `Nothing` if they are not. If set to `Nothing` (the default argument),
+         `Ordering.compare _ _` method will be used.
+       - on_incomparable: A `Problem_Behavior` specifying what should happen if
+         two incomparable values are encountered.
+
+       By default, elements are sorted in ascending order.
 
-       By default, elements are sorted in ascending order, using the comparator
-       acquired from each element. A custom compare function may be passed to
-       the sort method.
 
        This is a stable sort, meaning that items that compare the same will not
        have their order changed by the sorting process.
@@ -178,12 +183,32 @@ type Array
          - *Average Time:* `O(n * log n)`
          - *Worst-Case Space:* `O(n)` additional
 
+       ? Incomparable values
+         Incomparable values are either values with different comparators or with
+         the same comparator returning `Nothing` from its `compare` method.
+         See the documentation of the `Ordering` module for more info.
+
        ? Implementation Note
          The sort implementation is based upon an adaptive, iterative mergesort
          that requires far fewer than `n * log(n)` comparisons when the array
          is partially sorted. When the array is randomly ordered, the
          performance is equivalent to a standard mergesort.
 
+       ? Multiple comparators
+         Elements with different comparators are incomparable by definition.
+         This case is handled by first grouping the `self` array into groups
+         with the same comparator, recursively sorting these groups, and then
+         merging them back together. The order of the sorted groups in the
+         resulting array is based on the order of fully qualified names of
+         the comparators in the `self` array, with the exception of the group
+         for the default comparator, which is always the first group.
+
+         Additionally, an `Incomparable_Values` dataflow error will be returned
+         if the `on_incomparable` parameter is set to `Problem_Behavior.Report_Error`,
+         or a warning attached if the `on_incomparable` parameter is set to
+         `Problem_Behavior.Report_Warning` in case of encountering incomparable
+         values.
+
          It takes equal advantage of ascending and descending runs in the array,
          making it much simpler to merge two or more sorted arrays: simply
          concatenate them and sort.
@@ -197,8 +222,17 @@ type Array
          Sorting an array of `Pair`s on the first element, descending.
 
              [Pair 1 2, Pair -1 8].to_array.sort Sort_Direction.Descending (_.first)
-    sort : Sort_Direction -> (Any -> Any) -> (Any -> Any -> Ordering) -> Vector Any ! Incomparable_Values
-    sort self (order = Sort_Direction.Ascending) (on = x -> x) (by = (Ordering.compare _ _)) = Vector.sort self order on by
+
+       > Example
+         Sorting an array with elements with different comparators. Values `1`
+         and `My_Type` have different comparators. `1` will be sorted before `My_Type`
+         because it has the default comparator, and warning will be attached to
+         the resulting array.
+
+             [My_Type.Value 'hello', 1].to_array.sort == [1, My_Type.Value 'hello'].to_array
+    sort : Sort_Direction -> (Any -> Any)|Nothing -> (Any -> Any -> (Ordering|Nothing))|Nothing -> Problem_Behavior -> Vector Any ! Incomparable_Values
+    sort self (order = Sort_Direction.Ascending) on=Nothing by=Nothing on_incomparable=Problem_Behavior.Ignore =
+        Vector.sort self order on by on_incomparable
 
     ## Creates a new `Vector` with only the specified range of elements from the
        input, removing any elements outside the range.

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Index_Sub_Range.enso

@@ -117,7 +117,7 @@ invert_range_selection ranges length needs_sorting =
    Empty subranges are discarded.
 sort_and_merge_ranges : Vector Range -> Vector Range
 sort_and_merge_ranges ranges =
-    sorted = ranges.filter (range-> range.is_empty.not) . sort on=(.start)
+    sorted = ranges.filter (range-> range.is_empty.not) . sort on=(_.start)
     if sorted.is_empty then [] else
         current_ref = Ref.new sorted.first
         builder = Vector.new_builder

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Numbers.enso

@@ -1,6 +1,7 @@
 import project.Data.Text.Text
 import project.Data.Locale.Locale
 import project.Errors.Common.Arithmetic_Error
+import project.Errors.Common.Incomparable_Values
 import project.Error.Error
 import project.Nothing.Nothing
 import project.Panic.Panic
@@ -279,6 +280,9 @@ type Number
 
     ## Checks equality of numbers, using an `epsilon` value.
 
+       ! Error Conditions
+         If either of the arguments is `Number.nan`, an `Incomparable_Values` error is raised.
+
        Arguments:
        - that: The number to check equality against.
        - epsilon: The value by which `self` and `that` can be separated by before
@@ -288,7 +292,7 @@ type Number
          Check if 1 is equal to 1.0000001 within 0.001.
 
              1.equals 1.0000001 epsilon=0.001
-    equals : Number -> Number -> Boolean
+    equals : Number -> Number -> Boolean ! Incomparable_Values
     equals self that epsilon=0.0 =
         (self == that) || ((self - that).abs <= epsilon)
 
@@ -457,54 +461,6 @@ type Decimal
     ^ : Number -> Number
     ^ self that = @Builtin_Method "Decimal.^"
 
-    ## Checks if this is greater than that.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is greater than 7.3.
-
-             10 > 7.3
-    > : Number -> Boolean
-    > self that = @Builtin_Method "Decimal.>"
-
-    ## Checks if this is greater than or equal to thatthat.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is greater than or equal to 7.3.
-
-             10 >= 7.3
-    >= : Number -> Boolean
-    >= self that = @Builtin_Method "Decimal.>="
-
-    ## Checks if this is less than that.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is less than 7.3.
-
-             10 < 7.3
-    < : Number -> Boolean
-    < self that = @Builtin_Method "Decimal.<"
-
-    ## Checks if this is less than or equal to thatthat.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10.4 is less than or equal to 7.
-
-             10.4 <= 7
-    <= : Number -> Boolean
-    <= self that = @Builtin_Method "Decimal.<="
-
     ## Computes the absolute value of this.
 
        The absolute value of a positive number is itself, while the absolute
@@ -682,54 +638,6 @@ type Integer
     ^ : Number -> Number
     ^ self that = @Builtin_Method "Integer.^"
 
-    ## Checks if this is greater than that.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is greater than 7.
-
-             10 > 7
-    > : Number -> Boolean
-    > self that = @Builtin_Method "Integer.>"
-
-    ## Checks if this is greater than or equal to thatthat.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is greater than or equal to 7.
-
-             10 >= 7
-    >= : Number -> Boolean
-    >= self that = @Builtin_Method "Integer.>="
-
-    ## Checks if this is less than that.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is less than 7.
-
-             10 < 7
-    < : Number -> Boolean
-    < self that = @Builtin_Method "Integer.<"
-
-    ## Checks if this is less than or equal to thatthat.
-
-       Arguments:
-       - that: The number to compare this against.
-
-       > Example
-         Checking if 10 is less than or equal to 7.
-
-             10 <= 7
-    <= : Number -> Boolean
-    <= self that = @Builtin_Method "Integer.<="
-
     ## Computes the absolute value of this.
 
        The absolute value of a positive number is itself, while the absolute
@@ -937,6 +845,7 @@ type Integer
 
     parse_builtin text radix = @Builtin_Method "Integer.parse"
 
+
 ## UNSTABLE
 
    A syntax error when parsing a double.

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Ordering.enso

@@ -27,7 +27,7 @@ from project.Data.Boolean import all
 
     ```
     type Comparator T
-        compare : T -> T -> (Ordering|Nothing)
+        compare : T -> T -> (Ordering|Nothing) ! Incomparable_Values
         hash : T -> Integer
     ```
 
@@ -170,7 +170,7 @@ type Ordering
     Greater
 
     ## Compares to values and returns an Ordering
-    compare : Any -> Any -> Ordering ! (Incomparable_Values | Type_Error)
+    compare : Any -> Any -> Ordering ! Incomparable_Values
     compare x y =
         if x < y then Ordering.Less else
             if x == y then Ordering.Equal else