Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

style-guide: Clarify version-sorting #127875

Merged
merged 1 commit into from
Jul 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading