What does it mean for `use` statements to be version sorted?

help
1

I was trying to find out if Rust had any guidelines regarding the order of use statements (i.e. what the order of workspace crates, std, and external crates should be). In doing so, I found the Rust Style guide which says that imports should be version sorted.

What does that mean? Sorted by the version in Cargo.toml?

2

Using the mdbook search functionality found me this:

(under “Sorting”, in Introduction – The Rust Style Guide)

In various cases, the default Rust style specifies to sort things. If not otherwise specified, such sorting should be "version sorting", which ensures that (for instance) x8 comes before x16 even though the character 1 comes before the character 8 .

For the purposes of the Rust style, to compare two strings for version-sorting:

  • Process both strings from beginning to end as two sequences of maximal-length chunks, where each chunk consists either of a sequence of characters other than ASCII digits, or a sequence of ASCII digits (a numeric chunk), and compare corresponding chunks from the strings.
  • To compare two numeric chunks, compare them by numeric value, ignoring leading zeroes. If the two chunks have equal numeric value, but different numbers of leading digits, and this is the first time this has happened for these strings, treat the chunks as equal (moving on to the next chunk) but remember which string had more leading zeroes.
  • To compare two chunks if both are not numeric, compare them by Unicode character lexicographically, with two exceptions:
    • _ (underscore) sorts immediately after (space) but before any other character. (This treats underscore as a word separator, as commonly used in identifiers.)
    • Unless otherwise specified, version-sorting should sort non-lowercase characters (characters that can start an UpperCamelCase identifier) before lowercase characters.
  • If the comparison reaches the end of the string and considers each pair of chunks equal:
    • If one of the numeric comparisons noted the earliest point at which one string had more leading zeroes than the other, sort the string with more leading zeroes first.
    • Otherwise, the strings are equal.
2 Likes
3

The large text that @steffahn brought explains the details, but maybe preamble from strverscmp would be easier to understand:

It's used by GNU ls and predates Rust by decades.

1 Like
4

A slight tangent, but rustfmt has a bunch of settings for formatting use-statements, if you are looking for automated formatting:

(The settings concerning use-statements all have imports in their name, AFAICT.)