Adds "isSorted", "isSorted(by: )" and "allEqual" to Comparable Sequence

[mcekr]

Description

Adds a "isSorted" and "isSorted(by: )" methods which return true when a sequence is in sorted order and "allEqual" which returns true if all the elements are equal to each other.

Detailed Design

extension Sequence where Element: Comparable {...}
let a = 0...10
let b = (0...10).reversed()
let c = Array(repeating: 42, count: 10)
a.isSorted() // returns true
b.isSorted(by: >) // returns true
c.allEqual() // returns true

Documentation Plan

Added some comments.

Test Plan

Test class included.

Source Impact

Adds new API.

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[timvermeulen]

These docs go right above the function signature, not below 🙂

[mcekr]

Yeah, didn't notice that, thanks

[xwu]

This name is confusing to me, as it reads like it could be related to elementsEqual. It also seems like it's straightforward enough that we don't necessarily need to provide it in a library if the building blocks are there.

[natecook1000]

I agree — let’s keep this addition focused on checking that a collection is sorted.

[timvermeulen]

After thinking about this for a little bit, I think it might be nice if isSorted(by: <=) would mean that each element is <= the next (i.e. the sequence is sorted), and isSorted(by: <) means that each element is strictly smaller than the next (i.e. the sequence is strictly sorted). isSorted() would then have to call isSorted(by: <=).

[natecook1000]

Thanks for this PR, @mcekr! Some notes below. Could you also look at adding a document describing the purpose for these additions to the Guides/ folder?

[natecook1000]

Two notes on this version:

1. Since this method takes a closure for comparisons, it doesn’t need to be in the constrained extension
2. For this kind of method, we mark the closure as throwing and the method itself as rethrows

[natecook1000]

It would be good to test an empty collection, to check sorted collections that includes repeats (e.g. [1, 1, 1, 2, 3]), and also to verify that isSorted returns false for unsorted collections.

[natecook1000]

I agree — let’s keep this addition focused on checking that a collection is sorted.

[natecook1000]

To follow the Swift documentation style, these doc comments should start with “Returns a Boolean value indicating whether...”

[natecook1000]

@timvermeulen I disagree on this point — to match the semantics of the other operations that take comparison predicates, isSorted() should have the same result as isSorted(by: <). It wouldn't make sense for this guarantee to not hold, for any predicate p:

let result = myCollection.sorted(by: p)
assert(result.isSorted(by: p))

[timvermeulen]

That's a pretty compelling argument! I believe the current implementation is incorrect then, if that's the semantics we're going for: false should be returned when areInIncreasingOrder(right, left), not when !areInIncreasingOrder(left, right).

Under these semantics, I believe isSorted(by: <=) would (counterintuitively) test whether the sequence is strictly sorted, which is... interesting. Something like .consecutivePairs().allSatisfy(<) might be a better way to write that.

[mcekr]

Thanks for this PR, @mcekr! Some notes below. Could you also look at adding a document describing the purpose for these additions to the Guides/ folder?

Sure

[mcekr]

@natecook1000 @timvermeulen In order to match the semantics of the other operations isSorted(by: <) and isSorted(by: <=) should return the same result. Solution looks like this

if let p = prev, !(!areInIncreasingOrder(element, p) || areInIncreasingOrder(p, element)) {
    return false
}

but is it acceptable?

[natecook1000]

@mcekr It's better to think of the comparison predicate as establishing a weak order over the Element type, rather than a predicate that consecutive elements need to pass. Using that order, we can say that a collection is sorted if none of the consecutive elements disrupt that order. Put the other way, a collection is not sorted if, for any pair of consecutive elements, the second element is ordered before the first:

if let p = prev, areInIncreasingOrder(element, p) {
    return false
}

@timvermeulen Passing <= as the comparison predicate is actually a programmer error! Since it's reflexive (i.e. (a <= a) == true), it doesn't establish a strict weak order, as is required.

[natecook1000]

Closing this for now, feel free to re-open when you're ready to discuss further. Thanks!