Skip to content

Commit

Permalink
style-guide: Clarify version-sorting
Browse files Browse the repository at this point in the history
Every time we apply version-sorting, we also say to sort non-lowercase before
lowercase. This seems likely to be what we'll want for future sorting,
as well. For simplicity, just incorporate that into the definition,
"unless otherwise specified".
  • Loading branch information
joshtriplett committed Jul 17, 2024
1 parent f00f850 commit 37257b4
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 21 deletions.
34 changes: 20 additions & 14 deletions src/doc/style-guide/src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,7 @@ fn baz() {}
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`. (If not otherwise specified, version-sorting is
lexicographical.)
before the character `8`.

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

Expand All @@ -132,12 +131,13 @@ For the purposes of the Rust style, to compare two strings for version-sorting:
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, except that `_` (underscore) sorts immediately
after ` ` (space) but before any other character. (This treats underscore as
a word separator, as commonly used in identifiers.)
- If the use of version sorting specifies further modifiers, such as sorting
non-lowercase before lowercase, apply those modifiers to the lexicographic
sort in this step.
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
Expand All @@ -157,7 +157,17 @@ leading zeroes.

As an example, version-sorting will sort the following strings in the order
given:
- `_ZYWX`
- `_ZYXW`
- `_abcd`
- `A2`
- `ABCD`
- `Z_YXW`
- `ZY_XW`
- `ZY_XW`
- `ZYXW`
- `ZYXW_`
- `a1`
- `abcd`
- `u_zzz`
- `u8`
- `u16`
Expand Down Expand Up @@ -190,11 +200,7 @@ given:
- `x86_64`
- `x86_128`
- `x87`
- `Z_YWX`
- `ZY_WX`
- `ZYW_X`
- `ZYWX`
- `ZYWX_`
- `zyxw`

### [Module-level items](items.md)

Expand Down
10 changes: 3 additions & 7 deletions src/doc/style-guide/src/items.md
Original file line number Diff line number Diff line change
Expand Up @@ -489,10 +489,8 @@ foo::{
A *group* of imports is a set of imports on the same or sequential lines. One or
more blank lines or other items (e.g., a function) separate groups of imports.

Within a group of imports, imports must be version-sorted, except that
non-lowercase characters (characters that can start an `UpperCamelCase`
identifier) must be sorted before lowercase characters. Groups of imports must
not be merged or re-ordered.
Within a group of imports, imports must be version-sorted. Groups of imports
must not be merged or re-ordered.

E.g., input:

Expand Down Expand Up @@ -520,9 +518,7 @@ re-ordering.
### Ordering list import

Names in a list import must be version-sorted, except that:
- `self` and `super` always come first if present,
- non-lowercase characters (characters that can start an `UpperCamelCase`
identifier) must be sorted before lowercase characters, and
- `self` and `super` always come first if present, and
- groups and glob imports always come last if present.

This applies recursively. For example, `a::*` comes before `b::a` but `a::b`
Expand Down

0 comments on commit 37257b4

Please sign in to comment.