From 37257b45e9030fa28cea1ac7c0a55bf78049a1f8 Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Wed, 17 Jul 2024 13:21:45 -0700
Subject: [PATCH] style-guide: Clarify version-sorting
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".
---
src/doc/style-guide/src/README.md | 34 ++++++++++++++++++-------------
src/doc/style-guide/src/items.md | 10 +++------
2 files changed, 23 insertions(+), 21 deletions(-)
diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md
index dce50ebf29c46..f42b9cb597843 100644
--- a/src/doc/style-guide/src/README.md
+++ b/src/doc/style-guide/src/README.md
@@ -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:
@@ -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
@@ -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`
@@ -190,11 +200,7 @@ given:
- `x86_64`
- `x86_128`
- `x87`
-- `Z_YWX`
-- `ZY_WX`
-- `ZYW_X`
-- `ZYWX`
-- `ZYWX_`
+- `zyxw`
### [Module-level items](items.md)
diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md
index c0628691b7734..8e1b1d80fb644 100644
--- a/src/doc/style-guide/src/items.md
+++ b/src/doc/style-guide/src/items.md
@@ -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:
@@ -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`