From 9b32d0ec956a96b68a3781ef3e2f53111a35a7dd Mon Sep 17 00:00:00 2001 From: Arun Raghavan Date: Fri, 28 Jun 2019 14:09:24 +0530 Subject: [PATCH] Explicitly document sort stability As not all users of this library might be aware of the affact that Array.prototype.sort() can be stable or unstable depending on the actual JavaScript runtime being used (and potentially the length of the array), let's explicitly document this to avoid people from getting tripped up. --- src/Data/Array.purs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/Data/Array.purs b/src/Data/Array.purs index 6349418a..3863504d 100644 --- a/src/Data/Array.purs +++ b/src/Data/Array.purs @@ -681,6 +681,9 @@ modifyAtIndices is f xs = -- | Sort the elements of an array in increasing order, creating a new array. -- | +-- | The underlying sort may or may not be stable, depending on your JavaScript +-- | runtime. +-- | -- | ```purescript -- | sort [2, -3, 1] = [-3, 1, 2] -- | ``` @@ -691,6 +694,9 @@ sort xs = sortBy compare xs -- | Sort the elements of an array in increasing order, where elements are -- | compared using the specified partial ordering, creating a new array. -- | +-- | The underlying sort may or may not be stable, depending on your JavaScript +-- | runtime. +-- | -- | ```purescript -- | compareLength a b = compare (length a) (length b) -- | sortBy compareLength [[1, 2, 3], [7, 9], [-2]] = [[-2],[7,9],[1,2,3]] @@ -707,6 +713,9 @@ sortBy comp xs = sortImpl comp' xs -- | Sort the elements of an array in increasing order, where elements are -- | sorted based on a projection -- | +-- | The underlying sort may or may not be stable, depending on your JavaScript +-- | runtime. +-- | -- | ```purescript -- | sortWith (_.age) [{name: "Alice", age: 42}, {name: "Bob", age: 21}] -- | = [{name: "Bob", age: 21}, {name: "Alice", age: 42}]