Skip to content

Documentation for sort_by (and related methods) is potentially self-contradictory #130122

Closed
@BatmanAoD

Description

@BatmanAoD

Location

slice::sort_by

Summary

Now that sort_by can panic when the ordering is not total, it seems confusing and misleading to me, if not technically wrong, to specifically provide a guarantee about the state of the slice after the operation:

...the resulting order of elements in the slice is unspecified. All original elements will remain in the slice and any possible modifications via interior mutability are observed in the input.

In general, I would assume that a guarantee like this only applies if the function returns normally rather than diverging, and thus that it implies the function will not diverge. I'm a bit confused about what the purpose of the guarantee even is; is the point just that, for the purpose of cleanup with drop and/or catch_unwind, the slice still contains all the same data? I can see how this would be important in the case of a Vec or other container with smart-pointer elements, but it also seems that in that case, the more straightforward guarantee is just that, if Vec::sort_by panics (for any reason), and this causes the Vec itself to be dropped, its drop method will still be able to properly drop all the elements it contains. Mentioning the "order of elements", though, seems to imply that a user might be able to continue using the slice (or vector) after the panic occurs, and I'm having a hard time thinking of a scenario where that would be useful.

And, of course, with panic=abort, control should never return to the caller at all when sort_by panics, so this guarantee is meaningless.

The other interpretation I can think of is that this is explaining what happens if the ordering is not total but the new logic doesn't catch it, so sort_by returns normally. If that's the case, this should be made explicit.

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-bugCategory: This is a bug.T-libsRelevant to the library team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions