Distinguish sort and sortInPlace. (#405)

* Distinguish sort and sortInPlace.

* Fix.

Author: AStepanov25

Changelog.md

@@ -5,6 +5,7 @@
 * Add `PriorityQueue` (#392).
 * Add support for Weak references (#388).
 * Clarify difference between `List` and `pure/List` in doc comments (#386).
+* **Breaking:** Rename `sort` to `sortInPlace`, add `sort` (#405).
 
 ## 1.0.0
 

src/List.mo

@@ -587,15 +587,15 @@ module {
   /// List.add(list, 3);
   /// List.add(list, 1);
   /// List.add(list, 2);
-  /// List.sort(list, Nat.compare);
+  /// List.sortInPlace(list, Nat.compare);
   /// assert List.toArray(list) == [1, 2, 3];
   /// ```
   ///
   /// Runtime: O(size * log(size))
   ///
   /// Space: O(size)
   /// *Runtime and space assumes that `compare` runs in O(1) time and space.
-  public func sort<T>(list : List<T>, compare : (T, T) -> Order.Order) {
+  public func sortInPlace<T>(list : List<T>, compare : (T, T) -> Order.Order) {
     if (size(list) < 2) return;
     let arr = toVarArray(list);
     VarArray.sortInPlace(arr, compare);
@@ -604,6 +604,31 @@ module {
     }
   };
 
+  /// Sorts the elements in the list according to `compare`.
+  /// Sort is deterministic, stable, and in-place.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// import Nat "mo:core/Nat";
+  ///
+  /// let list = List.empty<Nat>();
+  /// List.add(list, 3);
+  /// List.add(list, 1);
+  /// List.add(list, 2);
+  /// let sorted = List.sort(list, Nat.compare);
+  /// assert List.toArray(sorted) == [1, 2, 3];
+  /// ```
+  ///
+  /// Runtime: O(size * log(size))
+  ///
+  /// Space: O(size)
+  /// *Runtime and space assumes that `compare` runs in O(1) time and space.
+  public func sort<T>(list : List<T>, compare : (T, T) -> Types.Order) : List<T> {
+    let array = toVarArray(list);
+    VarArray.sortInPlace(array, compare);
+    fromVarArray(array)
+  };
+
   /// Finds the first index of `element` in `list` using equality of elements defined
   /// by `equal`. Returns `null` if `element` is not found.
   ///

test/List.test.mo

@@ -811,7 +811,7 @@ run(
     [
       test(
         "sort",
-        List.sort<Nat>(list, Nat.compare) |> List.toArray(list),
+        List.sortInPlace<Nat>(list, Nat.compare) |> List.toArray(list),
         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] |> M.equals(T.array(T.natTestable, _))
       )
     ]
@@ -1134,9 +1134,15 @@ func testReverse(n : Nat) : Bool {
 };
 
 func testSort(n : Nat) : Bool {
-  let vec = List.fromArray<Int>(Array.tabulate<Int>(n, func(i) = (i * 123) % 100 - 50));
-  List.sort(vec, Int.compare);
-  List.equal(vec, List.fromArray<Int>(Array.sort(Array.tabulate<Int>(n, func(i) = (i * 123) % 100 - 50), Int.compare)), Int.equal)
+  let array = Array.tabulate<Int>(n, func(i) = (i * 123) % 100 - 50);
+  let vec = List.fromArray<Int>(array);
+
+  let sorted = List.sort(vec, Int.compare);
+  List.sortInPlace(vec, Int.compare);
+
+  let expected = List.fromArray<Int>(Array.sort(array, Int.compare));
+
+  List.equal(vec, expected, Int.equal) and List.equal(sorted, expected, Int.equal)
 };
 
 func testToArray(n : Nat) : Bool {

validation/api/api.lock.json

@@ -559,7 +559,8 @@
       "public func reverseValues<T>(list : List<T>) : Iter.Iter<T>",
       "public func singleton<T>(element : T) : List<T>",
       "public func size<T>(list : List<T>) : Nat",
-      "public func sort<T>(list : List<T>, compare : (T, T) -> Order.Order)",
+      "public func sort<T>(list : List<T>, compare : (T, T) -> Types.Order) : List<T>",
+      "public func sortInPlace<T>(list : List<T>, compare : (T, T) -> Order.Order)",
       "public func toArray<T>(list : List<T>) : [T]",
       "public func toPure<T>(list : List<T>) : PureList.List<T>",
       "public func toText<T>(list : List<T>, f : T -> Text) : Text",