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.

Sign up for GitHub

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

Rework range pattern rules #1756

Merged
merged 7 commits into from
Mar 18, 2025
Merged

Rework range pattern rules #1756

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a84ea27
add RangeToExclusivePattern to the reference
m4rch3n1ng Mar 2, 2025
18e422e
Include all range types in the _RangePattern_ production
ehuss Mar 3, 2025
9628f6b
Add note about _ObsoleteRangePattern_ being edition-specific.
ehuss Mar 3, 2025
5ac1ad0
Drop mention of `...` since it is no longer supported in the latest e…
ehuss Mar 12, 2025
43c4bac
Move the definition of bounds to the intro
ehuss Mar 12, 2025
d42bb62
Fix patterns.range.constraint-slice
ehuss Mar 12, 2025
daa1992
Rework range pattern rules
ehuss Mar 12, 2025
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
87 changes: 51 additions & 36 deletions src/patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -478,10 +478,12 @@ r[patterns.range]
r[patterns.range.syntax]
> **<sup>Syntax</sup>**\
> _RangePattern_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; _RangeInclusivePattern_\
> &nbsp;&nbsp; &nbsp;&nbsp; _RangeExclusivePattern_\
> &nbsp;&nbsp; | _RangeInclusivePattern_\
> &nbsp;&nbsp; | _RangeFromPattern_\
> &nbsp;&nbsp; | _RangeToExclusivePattern_\
> &nbsp;&nbsp; | _RangeToInclusivePattern_\
> &nbsp;&nbsp; | _ObsoleteRangePattern_
> &nbsp;&nbsp; | _ObsoleteRangePattern_[^obsolete-range-edition]
>
> _RangeExclusivePattern_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; _RangePatternBound_ `..` _RangePatternBound_
Expand All @@ -492,6 +494,9 @@ r[patterns.range.syntax]
> _RangeFromPattern_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; _RangePatternBound_ `..`
>
> _RangeToExclusivePattern_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; `..` _RangePatternBound_
>
> _RangeToInclusivePattern_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; `..=` _RangePatternBound_
>
Expand All @@ -504,69 +509,75 @@ r[patterns.range.syntax]
> &nbsp;&nbsp; | `-`<sup>?</sup> [INTEGER_LITERAL]\
> &nbsp;&nbsp; | `-`<sup>?</sup> [FLOAT_LITERAL]\
> &nbsp;&nbsp; | [_PathExpression_]
>
> [^obsolete-range-edition]: The _ObsoleteRangePattern_ syntax has been removed in the 2021 edition.

r[patterns.range.intro]
*Range patterns* match scalar values within the range defined by their bounds.
They comprise a *sigil* (one of `..`, `..=`, or `...`) and a bound on one or both sides.
They comprise a *sigil* (`..` or `..=`) and a bound on one or both sides.

r[patterns.range.lower-bound]
A bound on the left of the sigil is a *lower bound*.
A bound on the left of the sigil is called a *lower bound*.
A bound on the right is called an *upper bound*.

r[patterns.range.upper-bound]
A bound on the right is an *upper bound*.
r[patterns.range.exclusive]
The *exclusive range pattern* matches all values from the lower bound up to, but not including the upper bound.
It is written as its lower bound, followed by `..`, followed by the upper bound.

r[patterns.range.closed]
A range pattern with both a lower and upper bound will match all values between and including both of its bounds.
It is written as its lower bound, followed by `..` for end-exclusive or `..=` for end-inclusive, followed by its upper bound.
For example, a pattern `'m'..'p'` will match only `'m'`, `'n'` and `'o'`, specifically **not** including `'p'`.

r[patterns.range.type]
The type of the range pattern is the type unification of its upper and lower bounds.
r[patterns.range.inclusive]
The *inclusive range pattern* matches all values from the lower bound up to and including the upper bound.
It is written as its lower bound, followed by `..=`, followed by the upper bound.

For example, a pattern `'m'..='p'` will match only the values `'m'`, `'n'`, `'o'`, and `'p'`.
Similarly, `'m'..'p'` will match only `'m'`, `'n'` and `'o'`, specifically **not** including `'p'`.

r[patterns.range.from]
The *from range pattern* matches all values greater than or equal to the lower bound.
It is written as its lower bound followed by `..`.

For example, `1..` will match any integer greater than or equal to 1, such as 1, 9, or 9001, or 9007199254740991 (if it is of an appropriate size), but not 0, and not negative numbers for signed integers.

r[patterns.range.to-exclusive]
The *to exclusive range pattern* matches all values less than the upper bound.
It is written as `..` followed by the upper bound.

For example, `..10` will match any integer less than 10, such as 9, 1, 0, and for signed integer types, all negative values.

r[patterns.range.to-inclusive]
The *to inclusive range pattern* matches all values less than or equal to the upper bound.
It is written as `..=` followed by the upper bound.

For example, `..=10` will match any integer less than or equal to 10, such as 10, 1, 0, and for signed integer types, all negative values.

r[patterns.range.constraint-less-than]
The lower bound cannot be greater than the upper bound.
That is, in `a..=b`, a &le; b must be the case.
For example, it is an error to have a range pattern `10..=0`.

r[patterns.range.open-below]
A range pattern with only a lower bound will match any value greater than or equal to the lower bound.
It is written as its lower bound followed by `..`, and has the same type as its lower bound.
For example, `1..` will match 1, 9, or 9001, or 9007199254740991 (if it is of an appropriate size), but not 0, and not negative numbers for signed integers.

r[patterns.range.open-above]
A range pattern with only an upper bound matches any value less than or equal to the upper bound.
It is written as `..=` followed by its upper bound, and has the same type as its upper bound.
For example, `..=10` will match 10, 1, 0, and for signed integer types, all negative values.

r[patterns.range.constraint-slice]
Range patterns with only one bound cannot be used as the top-level pattern for subpatterns in [slice patterns](#slice-patterns).

r[patterns.range.bound]
The bounds is written as one of:
A bound is written as one of:

* A character, byte, integer, or float literal.
* A `-` followed by an integer or float literal.
* A [path]

r[patterns.range.constraint-bound-path]
If the bounds is written as a path, after macro resolution, the path must resolve to a constant item of the type `char`, an integer type, or a float type.
If a bound is written as a path, after macro resolution, the path must resolve to a constant item of the type `char`, an integer type, or a float type.

r[patterns.range.value]
The type and value of the bounds is dependent upon how it is written out.
r[patterns.range.type]
The range pattern matches the type of its upper and lower bounds, which must be the same type.

r[patterns.range.path-value]
If the bounds is a [path], the pattern has the type and value of the [constant] the path resolves to.

r[patterns.range.float-restriction]
For float range patterns, the constant may not be a `NaN`.
If a bound is a [path], the bound matches the type and has the value of the [constant] the path resolves to.

r[patterns.range.literal-value]
If it is a literal, it has the type and value of the corresponding [literal expression].
If a bound is a literal, the bound matches the type and has the value of the corresponding [literal expression].

r[patterns.range.negation]
If is a literal preceded by a `-`, it has the same type as the corresponding [literal expression] and the value of [negating] the value of the corresponding literal expression.
If a bound is a literal preceded by a `-`, the bound matches the same type as the corresponding [literal expression] and has the value of [negating] the value of the corresponding literal expression.

r[patterns.range.float-restriction]
For float range patterns, the constant may not be a `NaN`.

Examples:

Expand Down Expand Up @@ -653,6 +664,10 @@ The range of values for an integer type is the closed range from its minimum to
r[patterns.range.refutable-char]
The range of values for a `char` type are precisely those ranges containing all Unicode Scalar Values: `'\u{0000}'..='\u{D7FF}'` and `'\u{E000}'..='\u{10FFFF}'`.

r[patterns.range.constraint-slice]
_RangeFromPattern_ cannot be used as a top-level pattern for subpatterns in [slice patterns](#slice-patterns).
For example, the pattern `[1.., _]` is not a valid pattern.

r[patterns.range.edition2021]
> **Edition differences**: Before the 2021 edition, range patterns with both a lower and upper bound may also be written using `...` in place of `..=`, with the same meaning.

Expand Down