Add examples for Ord and PartialOrd traits in std docs

[mdinger]

Trait Ord and PartialOrd have cryptic explanations. An example would be helpful.

I thought these would be valid examples:

// [1,2,3,4,5,6] -> Ord - sortable without duplicates
// [B,C,D,a,c,e] -> Ord (used ASCII ordering)
// [1,1,1,2,3,3] -> PartialOrd - sortable with duplicates
// [A,B,B,c,c,c] -> PartialOrd

@steveklabnik You asked to be CCed on documentation bugs

[thestinger]

Ord vs. PartialOrd has to do with whether the types have unordered values. It has nothing to do with duplicates in sequences, traits are properties of type. I think the explanation is pretty good.

[mdinger]

I missed that total order has a == b allowed and I misunderstood something on PartialOrd. I actually feed kinda dumb for missing that. I still think total order will be unknown to many and throwing syntax below to clarify makes it more cryptic than it should be. An example list of the different types would clarify. Is this more accurate?

// [1,A,a,3,3  ,b,b,4,7]   -> Ord - elements are completely sortable
// [1,A,a,3,NaN,b,b,4,NaN] -> PartialOrd - elements are partially sortable
//           ^         ^ Cannot be sorted

Note: I'm not remarking about the accuracy or precision of the definition. Just ease of comprehension.

[thestinger]

It doesn't have anything to do with the values contained in a specific array. As with all traits, it's a property of types.

[mdinger]

The type must fit with this total order concept though correct? That is, [1,A,a,3,NaN,b,b,4,NaN] would not be total order because it isn't completely sortable. Therefore you could never apply Ord to a type like this, correct?

[sfackler]

A total ordering is a property of a type, not an array. f32 is not totally ordered. The inability to sort is one result of that fact.

[mdinger]

@sfackler explained how my examples were ambiguous and I have used his explanation/examples to revise the example below. @thestinger, his explanation also also explained your comments which I didn't understand before.

// A `type` which forms a total order is completely sortable
// `i32` forms a Total Order
let _entirelySortable = [1i32, -1, 7, 3, 5, 9]; // Sortable because `i32` is

// `f32` does not form a Total Order
let _partiallySortable1 = [1.0f32, -1.0, 7.0, std::f32::NAN];
// NAN's sorting order is undefined making this `type` unsortable
// (Is NAN before or after 3?)

// Still unsortable because `f32` supports NAN
let _partiallySortable2 = [1.0f32, -1.0, 7.0, 14.2]; // Also, not a total order

My issue with the Ord page is without understanding Total order, it's difficult to know what it's talking about without thinking through that math example. If you look at #15217 where they assume people don't know the [from,to) range notation, I think it's safe to assume the same people won't immediately translate (which is much harder than understanding the range notation by the way):

An order is a total order if it is (for all a, b and c):

• total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
• transitive, a < b and b < c implies a < c. The same must hold for both == and >.

Into: "Ah! This type has one unique sorting order with no exceptions! Obviously, if there is an exception, I have to use PartialOrd instead". The definition is certainly precise but it should be more readable (or have an example). Also, the range notation is much simpler and obvious once you know it.

The issue with PartialOrd is that knowing what to use it for depends on knowing what Ord cannot be used for. I think making Ord more readable would be helpful. I grouped them together because they are related and an example in one could possibly be duplicated in the other because it is probably still pertinent.

[EDIT]
Not arguing that Rust should cater to those who don't understand [from, to) notation. Just trying to point out that it's a little cryptic.

[steveklabnik]

I don't think this is particularly actionable, or at least, any more than a general "most docs can be improved" kind of way. While they may be short, they are accurate, so I'm going to close this.

Concrete improvements to any docs, including these docs, are welcome.