diff options
| -rw-r--r-- | src/doc/style-guide/src/README.md | 91 |
1 files changed, 69 insertions, 22 deletions
diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md index d00e6a5d882..b8193891b13 100644 --- a/src/doc/style-guide/src/README.md +++ b/src/doc/style-guide/src/README.md @@ -109,32 +109,79 @@ lexicographical.) For the purposes of the Rust style, to compare two strings for version-sorting: -- Compare the strings by (Unicode) character lexicographically, finding the - index of the first differing character. (If the two strings do not have the - same length, this may be the end of the shorter string.) -- For both strings, determine the longest sequence of ASCII digits that either - contains or ends at that index. (If either string doesn't have such a - sequence of ASCII digits, fall back to comparing the strings - lexicographically.) -- Compare the numeric values of the number specified by the sequence of digits. - (Note that an implementation of this algorithm can easily check this without - accumulating copies of the digits or converting to a number: after skipping - leading zeroes, longer sequences of digits are larger numbers, and - equal-length sequences of digits can be sorted lexicographically.) -- If the numbers have the same numeric value, the one with more leading zeroes - comes first. - -Note that there exist various algorithms called "version sorting", which differ -most commonly in their handling of numbers with leading zeroes. This algorithm +- 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, 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. +- 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. + +Note that there exist various algorithms called "version sorting", which +generally try to solve the same problem, but which differ in various ways (such +as in their handling of numbers with leading zeroes). This algorithm does not purport to precisely match the behavior of any particular other algorithm, only to produce a simple and satisfying result for Rust formatting. -(In particular, this algorithm aims to produce a satisfying result for a set of +In particular, this algorithm aims to produce a satisfying result for a set of symbols that have the same number of leading zeroes, and an acceptable and easily understandable result for a set of symbols that has varying numbers of -leading zeroes.) - -As an example, version-sorting will sort the following symbols in the order -given: `x000`, `x00`, `x0`, `x01`, `x1`, `x09`, `x9`, `x010`, `x10`. +leading zeroes. + +As an example, version-sorting will sort the following strings in the order +given: +- `_ZYWX` +- `u_zzz` +- `u8` +- `u16` +- `u32` +- `u64` +- `u128` +- `u256` +- `ua` +- `usize` +- `uz` +- `v000` +- `v00` +- `v0` +- `v0s` +- `v00t` +- `v0u` +- `v001` +- `v01` +- `v1` +- `v009` +- `v09` +- `v9` +- `v010` +- `v10` +- `w005s09t` +- `w5s009t` +- `x64` +- `x86` +- `x86_32` +- `x86_64` +- `x86_128` +- `x87` +- `Z_YWX` +- `ZY_WX` +- `ZYW_X` +- `ZYWX` +- `ZYWX_` ### [Module-level items](items.md) |