Documentation for sorting #1568
Conversation
There was a problem hiding this comment.
Thanks for being so thorough about all those semantics.
Maybe some of it is very thorough for end-user documentation but I think it is good if we start out with well documented/specified semantics. We can still move the details to the reference material and have a simpler intro at a later point in time.
| If you _do_ want a sort containing differing types to error, see [strict sort](#strict-sort). | ||
| ::: | ||
|
|
||
| Nushell's sort is also **stable**, meaning equal values will retain their original ordering relative to each other. This is illustrated here using the [insensitive](#insensitive-sort) sort option: |
There was a problem hiding this comment.
Do we want to commit to all our sorting implementations being stable or should that be relaxed to sort or "stable by default"?
For clarity I would specify the insensitive
| Nushell's sort is also **stable**, meaning equal values will retain their original ordering relative to each other. This is illustrated here using the [insensitive](#insensitive-sort) sort option: | |
| Nushell's sort is also **stable**, meaning equal values will retain their original ordering relative to each other. This is illustrated here using the [case insensitive](#insensitive-sort) sort option: |
There was a problem hiding this comment.
sort and sort-by both use Rust's sort_by, which is stable. I also have a unit test which does something similar to the example here which demonstrates the sort being stable. I'm not sure what other sorting implementation there might be?
I agree, I'll rename the heading to "case insensitive" as well.
| ╰───┴────────╯ | ||
| ``` | ||
|
|
||
| We can see that the numbers are sorted in order, and the strings are sorted to the end of the list, also in order. If you are coming from other programming languages, this may not be quite what you expect. In Nushell, as a general rule, **data can always be sorted without erroring**. |
There was a problem hiding this comment.
Some part of my inner "language patent lawyer" thinks that promising this leads to some tricky rules to define a total order over all data types with challenges as soon as new types would be introduced and are messy to teach if you run into them. But for the general usability it is definitely a bonus if you don't have to worry about this.
There was a problem hiding this comment.
At least currently, there is indeed an ordering between all types. It's effectively the order of the Value enum's variants, with some exceptions. As I see it, the tradeoff here is between "sort which errors on mixed types" or "sort that never errors". Personally, if it would be possible for sort to error because of incompatible types, I would rather make it fully strict at that point.
I wasn't planning on specifying what order the types would be, except maybe that within the same version of Nushell the ordering between types is always the same. I would like to guarantee at least that null comes at the end, and the corresponding Nushell PR does do this. Since Nothing is kind of a special type, and you might expect it to appear a lot more than say, an integer and a string, I think it's a useful property for it to always appear at the end.
Companion PR to nushell/nushell#13154. Should not be merged until the nushell PR is merged.
Adds a new page to the book explaining how Nushell's many different sorting behaviors work, including old features and new features.