Improve documentation of sort

[bkamins]

Following issue #26741 I have another problem with sort when using order argument. Consider the following inconsistency as an example (similar thing is present with lt):

julia> sort([1,-1,2], by=identity, order=Base.By(abs))
3-element Array{Int64,1}:
  1
 -1
  2

julia> sort([1,-1,2], by=x->-x, order=Base.By(abs))
3-element Array{Int64,1}:
  2
  1
 -1

In the first case, following the implementation in ordering.jl, Julia ignores by argument in the first case, because it is equal to the default and in the second case it respects it.

In general order argument is not documented well and it defaults to a non-exported value.
I am not sure, given we are in 0.7.0-alpha stage if this should be:

• fixed (e.g. by not exposing order argument in public API)
  or
• only documented precisely describing the way it works (or at least saying to either use lt, by and rev or order keyword argument)?

[haampie]

See also #22388 (comment) and the corresponding issue #22382.

---

Edit: the following digresses a bit form the point of this issue, but still.

I think we're pretty close to resolving the whole sort API problem altogether. There's @nalimilan's PR #22388 that deprecates the order keyword, and there's some work haampie@b65740d I have that radically implements the ideas of #26741 everywhere. There's only a decision to be made about what the API really should look like.

My question would be: can we make some minimal changes right now, so that we can resolve the full issue (order keyword not making sense, rev = true/false being type unstable, Order not being composable) during Julia 1.0 in a non-breaking way?

[haampie]

Crazy idea: for the whole zoo of sort-related functions deprecate the signature

sort(x, by = b, lt = l, rev = r)

to a positional argument

sort(x, ord(by = b, lt = l, rev = r))

Deprecate

sort(x, order = o)

to

sort(x, o)

This avoids (1) the type instability within the sort function -- only ord is type unstable now, and (2) it avoids the incompatibility between the kwargs. Then advocate the use of Order instances in most cases. Export some sensible defaults:

sort(x, rev = true)

becomes

# Backward = Rev(Forward), Forward = Lt(isless)
sort(x, Backward)

And make Order objects fully compositional. The following type-unstable call

sort(x, lt = my_op, rev = true, by = abs)

can be written in a stable way as

sort(x, Rev(By(abs, Lt(my_op))))

[bkamins]

Given the number of open issues for sort API its consistency should be improved in my opinion. The question to core-devs is if it would be allowed at this stage.

[StefanKarpinski]

Good thoughts but not gonna happen in 0.7/1.0; we're trying to get 0.7-beta out quite soon.

[LilithHafner]

The observed inconsistency in the OP is due to the fact that the by is applied in addition to, not instead of, the order keyword. That is, sort(v, by=f, order=By(g, Forward)) is equivalent to sort(v, by=g∘f).

[bkamins]

My key point was, as noted in the title, that I do not find a clear documentation how different arguments interact (but maybe I missed something in the manual).

[LilithHafner]

My comment was to help whomever documents this behavior not to invalidate the issue