From 1fcde97462440f149f976b8fb0b5d08a0933d7e8 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Mon, 20 Apr 2026 17:05:22 +0200 Subject: [PATCH 01/26] document Closure capture precision --- src/changelog.rst | 24 ++++++++++++++ src/types-and-traits.rst | 68 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) diff --git a/src/changelog.rst b/src/changelog.rst index 8ea20f53..98d5e36b 100644 --- a/src/changelog.rst +++ b/src/changelog.rst @@ -39,6 +39,30 @@ Language changes in Rust 1.95.0 - `Make operational semantics of pattern matching independent of crate and module `_ + New paragraphs, which mostly document behavior that existed before this release: + + - :p:`fls_rdDT7jsaOMbs` + - :p:`fls_j9WyKVyOLFon` + - :p:`fls_TbfUxVf8PKPs` + - :p:`fls_4TESOxGpEY2h` + - :p:`fls_eNkZWskzznW6` + - :p:`fls_v8IFXHJnXhez` + - :p:`fls_gujpU7p5n9Zx` + - :p:`fls_t8tFLUg8O83Q` + - :p:`fls_RaONmCLH2KGM` + - :p:`fls_Vt9C9mKxHOwo` + - :p:`fls_Fs12dmznjsMf` + - :p:`fls_7EXHdE2eOVek` + - :p:`fls_iLH8X2U4ADHb` + - :p:`fls_HMJUXHrvOmPl` + - :p:`fls_Gj1znNpthHY6` + - :p:`fls_IFyJvb6mlFU4` + - :p:`fls_7NEEJgKSpQQ8` + - :p:`fls_kYFd3p06pWWV` + - :p:`fls_fATMTNUOHsfb` + - :p:`fls_fITor3jpmgrl` + - :p:`fls_XFwPNGsVsu05` + FLS corrections --------------- diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 73768350..3fac0806 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -903,6 +903,74 @@ A :t:`closure type` implicitly implements the :std:`core::marker::Sync` :t:`trait` if all the :t:`[type]s` of the :t:`[value]s` of the :t:`capturing environment` implement the :std:`core::marker::Send` :t:`trait`. +.. _fls_G64vdcIyB2Is: + +Closure capture precision +^^^^^^^^^^^^^^^^^^^^^^^^^ + +:dp:`fls_rdDT7jsaOMbs` +A :dt:`capture path` is a sequence starting with a :t:`variable` from the environment followed by zero or more :t:`[place projection]s` from that variable. + +:dp:`fls_j9WyKVyOLFon` +A :dt:`place projection` is a :t:`field access expression`, tuple :t:`field access expression`, :t:`dereference`, array or slice :t:`index expression`, or :t:`pattern` destructuring applied to a variable. + +:dp:`fls_TbfUxVf8PKPs` +The closure :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: + +- :dp:`fls_4TESOxGpEY2h` + When a :t:`capture path` and one of the ancestors of that path are both captured by a closure, the ancestor path is captured with the highest capture mode among the two captures, using the strict weak ordering: :t:`immutable borrow` < :t:`unique immutable borrow` < :t:`mutable borrow` < :t:`move `. + +- :dp:`fls_eNkZWskzznW6` + The :t:`capture path` is truncated at the rightmost :t:`dereference` in the capture path if the dereference is applied to a :t:`shared reference`. + +:dp:`fls_v8IFXHJnXhez` +A :t:`place` is not captured when an :t:`underscore expression` is used to bind it. + +:dp:`fls_gujpU7p5n9Zx` +A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums. + +:dp:`fls_t8tFLUg8O83Q` +A :t:`place` is not captured by being matched against a :t:`rest pattern`. + +:dp:`fls_RaONmCLH2KGM` +The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing `, or :t:`slicing `. + +:dp:`fls_Vt9C9mKxHOwo` +A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`. + +:dp:`fls_Fs12dmznjsMf` +Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`. + +:dp:`fls_7EXHdE2eOVek` +Matching against a variant of an enum that has one variant does not capture the place, unless is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`. + +:dp:`fls_iLH8X2U4ADHb` +Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`. + +:dp:`fls_HMJUXHrvOmPl` +Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`. + +:dp:`fls_Gj1znNpthHY6` +Matching an array against a slice pattern does not capture the :t:`place`. + +:dp:`fls_IFyJvb6mlFU4` +Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. + +:dp:`fls_7NEEJgKSpQQ8` +Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. + +:dp:`fls_kYFd3p06pWWV` +Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to union itself. + +:dp:`fls_fATMTNUOHsfb` +Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unalidged :t:`[field]s` in a struct. + +:dp:`fls_fITor3jpmgrl` +Taking the address of an unaligned :t:`field` captures the entire struct. + +:dp:`fls_XFwPNGsVsu05` +A :dt:`unique immutable borrow` is a capture that occurs when modifying the :t:`referent` of a :t:`mutable reference`. + .. _fls_airvr79xkcag: Function Item Types From ab0c74dd17a9ce1100740d08e6d3bb71346d3d59 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Mon, 20 Apr 2026 19:33:59 +0200 Subject: [PATCH 02/26] typo Co-authored-by: Ana Hobden --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 3fac0806..cd239e32 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -963,7 +963,7 @@ Closures will only capture the prefix of a :t:`capture path` that runs up to, bu Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to union itself. :dp:`fls_fATMTNUOHsfb` -Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unalidged :t:`[field]s` in a struct. +Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct. :dp:`fls_fITor3jpmgrl` Taking the address of an unaligned :t:`field` captures the entire struct. From c128b745329dd8c2136dbeed1052c28c69cacd2d Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 11:34:34 +0200 Subject: [PATCH 03/26] use a defined term Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index cd239e32..7d909331 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -909,7 +909,7 @@ Closure capture precision ^^^^^^^^^^^^^^^^^^^^^^^^^ :dp:`fls_rdDT7jsaOMbs` -A :dt:`capture path` is a sequence starting with a :t:`variable` from the environment followed by zero or more :t:`[place projection]s` from that variable. +A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. :dp:`fls_j9WyKVyOLFon` A :dt:`place projection` is a :t:`field access expression`, tuple :t:`field access expression`, :t:`dereference`, array or slice :t:`index expression`, or :t:`pattern` destructuring applied to a variable. From f07211978938bfe812cd36bcf417e7119286b035 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 11:40:38 +0200 Subject: [PATCH 04/26] remove a redundancy, and add some links Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 7d909331..88a97491 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -912,7 +912,7 @@ Closure capture precision A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. :dp:`fls_j9WyKVyOLFon` -A :dt:`place projection` is a :t:`field access expression`, tuple :t:`field access expression`, :t:`dereference`, array or slice :t:`index expression`, or :t:`pattern` destructuring applied to a variable. +A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`. :dp:`fls_TbfUxVf8PKPs` The closure :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: From 88e7bbf17c216a85fc6f8a68f477e79e3cda382f Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 11:44:23 +0200 Subject: [PATCH 05/26] grammar and consistency fix --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 88a97491..6bff6239 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -915,7 +915,7 @@ A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`ca A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`. :dp:`fls_TbfUxVf8PKPs` -The closure :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: +A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: - :dp:`fls_4TESOxGpEY2h` When a :t:`capture path` and one of the ancestors of that path are both captured by a closure, the ancestor path is captured with the highest capture mode among the two captures, using the strict weak ordering: :t:`immutable borrow` < :t:`unique immutable borrow` < :t:`mutable borrow` < :t:`move `. From a983ac12cbe1418c94838b2b35cf03fa369d9f11 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 11:49:35 +0200 Subject: [PATCH 06/26] link-it Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 6bff6239..07bfa61d 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -921,7 +921,7 @@ A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture When a :t:`capture path` and one of the ancestors of that path are both captured by a closure, the ancestor path is captured with the highest capture mode among the two captures, using the strict weak ordering: :t:`immutable borrow` < :t:`unique immutable borrow` < :t:`mutable borrow` < :t:`move `. - :dp:`fls_eNkZWskzznW6` - The :t:`capture path` is truncated at the rightmost :t:`dereference` in the capture path if the dereference is applied to a :t:`shared reference`. + The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. :dp:`fls_v8IFXHJnXhez` A :t:`place` is not captured when an :t:`underscore expression` is used to bind it. From eefb10d1a3c15d562cb310d5b27dbcfa68ee54dd Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 13:28:46 +0200 Subject: [PATCH 07/26] define the term before using it --- src/types-and-traits.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 07bfa61d..c479f023 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -908,12 +908,12 @@ environment` implement the :std:`core::marker::Send` :t:`trait`. Closure capture precision ^^^^^^^^^^^^^^^^^^^^^^^^^ -:dp:`fls_rdDT7jsaOMbs` -A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. - :dp:`fls_j9WyKVyOLFon` A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`. +:dp:`fls_rdDT7jsaOMbs` +A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. + :dp:`fls_TbfUxVf8PKPs` A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: From f502ea25f2d16417dc07350289457c8fc14e1adf Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 13:35:28 +0200 Subject: [PATCH 08/26] be more consise and clear, remove redundancy, and link to a definition --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index c479f023..e4f4d099 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -918,7 +918,7 @@ A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`ca A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: - :dp:`fls_4TESOxGpEY2h` - When a :t:`capture path` and one of the ancestors of that path are both captured by a closure, the ancestor path is captured with the highest capture mode among the two captures, using the strict weak ordering: :t:`immutable borrow` < :t:`unique immutable borrow` < :t:`mutable borrow` < :t:`move `. + When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest capture mode among the two :t:`[capture path]s`. - :dp:`fls_eNkZWskzznW6` The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. From 90678f76f59872bfbe0d7990cf9c3619179a404f Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 13:41:35 +0200 Subject: [PATCH 09/26] be more consise and clear, remove redundancy, and link to some definitions --- src/types-and-traits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index e4f4d099..8790b1c3 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -918,7 +918,7 @@ A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`ca A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: - :dp:`fls_4TESOxGpEY2h` - When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest capture mode among the two :t:`[capture path]s`. + When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`. - :dp:`fls_eNkZWskzznW6` The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. From 2d0f3faffa8eda818f65a318608d38958d4411dc Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 13:44:22 +0200 Subject: [PATCH 10/26] clarity --- src/changelog.rst | 5 +++++ src/expressions.rst | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/src/changelog.rst b/src/changelog.rst index 98d5e36b..75f9e4c8 100644 --- a/src/changelog.rst +++ b/src/changelog.rst @@ -39,6 +39,11 @@ Language changes in Rust 1.95.0 - `Make operational semantics of pattern matching independent of crate and module `_ + Changed paragraphs: + + - :p:`fls_33hfay24hx8u` + - :p:`fls_uqy5w9uc8gla` + New paragraphs, which mostly document behavior that existed before this release: - :p:`fls_rdDT7jsaOMbs` diff --git a/src/expressions.rst b/src/expressions.rst index e9696884..ead3f501 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5153,7 +5153,7 @@ within the :t:`capturing expression`, as follows: precedence: #. :dp:`fls_33hfay24hx8u` - :t:`By immutable reference capture`. + :t:`By immutable reference capture` (lowest precedence). #. :dp:`fls_wmxsd0i2yemf` :t:`By unique immutable reference capture` mode, if the @@ -5163,7 +5163,7 @@ within the :t:`capturing expression`, as follows: :t:`By mutable reference capture` mode. #. :dp:`fls_uqy5w9uc8gla` - :t:`By value capture`. + :t:`By value capture` (highest precedence). :dp:`fls_wvob7114tfat` A tool selects the first :t:`capture mode` that is compatible with the use of From d10964929794683d8206b146e03f1b937d08c855 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 15:27:24 +0200 Subject: [PATCH 11/26] missing word --- src/types-and-traits.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 8790b1c3..e9a4b23a 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -942,7 +942,7 @@ A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is re Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`. :dp:`fls_7EXHdE2eOVek` -Matching against a variant of an enum that has one variant does not capture the place, unless is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`. +Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`. :dp:`fls_iLH8X2U4ADHb` Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`. @@ -960,7 +960,7 @@ Move closures can only capture the prefix of a :t:`capture path` that runs up to Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. :dp:`fls_kYFd3p06pWWV` -Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to union itself. +Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself. :dp:`fls_fATMTNUOHsfb` Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct. From d6115188549b53df25c69d9c95bfb0903cf6cf73 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 15:29:34 +0200 Subject: [PATCH 12/26] dangling term --- src/changelog.rst | 1 - src/types-and-traits.rst | 3 --- 2 files changed, 4 deletions(-) diff --git a/src/changelog.rst b/src/changelog.rst index 75f9e4c8..525fef0f 100644 --- a/src/changelog.rst +++ b/src/changelog.rst @@ -66,7 +66,6 @@ Language changes in Rust 1.95.0 - :p:`fls_kYFd3p06pWWV` - :p:`fls_fATMTNUOHsfb` - :p:`fls_fITor3jpmgrl` - - :p:`fls_XFwPNGsVsu05` FLS corrections --------------- diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index e9a4b23a..7fae19f8 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -968,9 +968,6 @@ Closures will only capture the prefix of the :t:`capture path` that runs up to, :dp:`fls_fITor3jpmgrl` Taking the address of an unaligned :t:`field` captures the entire struct. -:dp:`fls_XFwPNGsVsu05` -A :dt:`unique immutable borrow` is a capture that occurs when modifying the :t:`referent` of a :t:`mutable reference`. - .. _fls_airvr79xkcag: Function Item Types From 74ce3c818468c5a758e8c95e7d865cfc6c47d322 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 21 Apr 2026 15:36:05 +0200 Subject: [PATCH 13/26] move to a more suitable place --- src/expressions.rst | 65 ++++++++++++++++++++++++++++++++++++++++ src/types-and-traits.rst | 65 ---------------------------------------- 2 files changed, 65 insertions(+), 65 deletions(-) diff --git a/src/expressions.rst b/src/expressions.rst index ead3f501..a4ef9be9 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5169,6 +5169,71 @@ within the :t:`capturing expression`, as follows: A tool selects the first :t:`capture mode` that is compatible with the use of the :t:`capture target`. +.. _fls_G64vdcIyB2Is: + +Capture precision +~~~~~~~~~~~~~~~~~ + +:dp:`fls_j9WyKVyOLFon` +A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`. + +:dp:`fls_rdDT7jsaOMbs` +A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. + +:dp:`fls_TbfUxVf8PKPs` +A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: + +- :dp:`fls_4TESOxGpEY2h` + When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`. + +- :dp:`fls_eNkZWskzznW6` + The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. + +:dp:`fls_v8IFXHJnXhez` +A :t:`place` is not captured when an :t:`underscore expression` is used to bind it. + +:dp:`fls_gujpU7p5n9Zx` +A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums. + +:dp:`fls_t8tFLUg8O83Q` +A :t:`place` is not captured by being matched against a :t:`rest pattern`. + +:dp:`fls_RaONmCLH2KGM` +The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing `, or :t:`slicing `. + +:dp:`fls_Vt9C9mKxHOwo` +A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`. + +:dp:`fls_Fs12dmznjsMf` +Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`. + +:dp:`fls_7EXHdE2eOVek` +Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`. + +:dp:`fls_iLH8X2U4ADHb` +Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`. + +:dp:`fls_HMJUXHrvOmPl` +Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`. + +:dp:`fls_Gj1znNpthHY6` +Matching an array against a slice pattern does not capture the :t:`place`. + +:dp:`fls_IFyJvb6mlFU4` +Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. + +:dp:`fls_7NEEJgKSpQQ8` +Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. + +:dp:`fls_kYFd3p06pWWV` +Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself. + +:dp:`fls_fATMTNUOHsfb` +Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct. + +:dp:`fls_fITor3jpmgrl` +Taking the address of an unaligned :t:`field` captures the entire struct. + .. _fls_ZfIBiJMf8qE1: Arithmetic Overflow diff --git a/src/types-and-traits.rst b/src/types-and-traits.rst index 7fae19f8..73768350 100644 --- a/src/types-and-traits.rst +++ b/src/types-and-traits.rst @@ -903,71 +903,6 @@ A :t:`closure type` implicitly implements the :std:`core::marker::Sync` :t:`trait` if all the :t:`[type]s` of the :t:`[value]s` of the :t:`capturing environment` implement the :std:`core::marker::Send` :t:`trait`. -.. _fls_G64vdcIyB2Is: - -Closure capture precision -^^^^^^^^^^^^^^^^^^^^^^^^^ - -:dp:`fls_j9WyKVyOLFon` -A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`. - -:dp:`fls_rdDT7jsaOMbs` -A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. - -:dp:`fls_TbfUxVf8PKPs` -A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: - -- :dp:`fls_4TESOxGpEY2h` - When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`. - -- :dp:`fls_eNkZWskzznW6` - The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. - -:dp:`fls_v8IFXHJnXhez` -A :t:`place` is not captured when an :t:`underscore expression` is used to bind it. - -:dp:`fls_gujpU7p5n9Zx` -A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums. - -:dp:`fls_t8tFLUg8O83Q` -A :t:`place` is not captured by being matched against a :t:`rest pattern`. - -:dp:`fls_RaONmCLH2KGM` -The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing `, or :t:`slicing `. - -:dp:`fls_Vt9C9mKxHOwo` -A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`. - -:dp:`fls_Fs12dmznjsMf` -Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`. - -:dp:`fls_7EXHdE2eOVek` -Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`. - -:dp:`fls_iLH8X2U4ADHb` -Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`. - -:dp:`fls_HMJUXHrvOmPl` -Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`. - -:dp:`fls_Gj1znNpthHY6` -Matching an array against a slice pattern does not capture the :t:`place`. - -:dp:`fls_IFyJvb6mlFU4` -Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. - -:dp:`fls_7NEEJgKSpQQ8` -Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. - -:dp:`fls_kYFd3p06pWWV` -Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself. - -:dp:`fls_fATMTNUOHsfb` -Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct. - -:dp:`fls_fITor3jpmgrl` -Taking the address of an unaligned :t:`field` captures the entire struct. - .. _fls_airvr79xkcag: Function Item Types From 5c2ae24b33f0d95837189703e158e87e450d19ec Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Thu, 23 Apr 2026 18:14:02 +0200 Subject: [PATCH 14/26] be less verbose (and nearly all the paragraphs are rules, so don't overload the term) Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions.rst b/src/expressions.rst index a4ef9be9..22656270 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5181,7 +5181,7 @@ A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. :dp:`fls_TbfUxVf8PKPs` -A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, which may be truncated based on these rules: +A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, as follows: - :dp:`fls_4TESOxGpEY2h` When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`. From 5b89a38d4d203925e1a9f32dbdaca82a93cd6eea Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Thu, 23 Apr 2026 18:21:19 +0200 Subject: [PATCH 15/26] link-it --- src/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions.rst b/src/expressions.rst index 22656270..62507d7f 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5184,7 +5184,7 @@ A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`ca A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture path`, as follows: - :dp:`fls_4TESOxGpEY2h` - When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`. + When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured `, the ancestor :t:`capture path` is :t:`captured` with the highest :t:`capture mode` among the two :t:`[capture path]s`. - :dp:`fls_eNkZWskzznW6` The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. From 3de56f1eb221623e41587e84d44bf4763f196bb8 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 28 Apr 2026 09:28:11 +0200 Subject: [PATCH 16/26] match FLS style, and re-oder one rule Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/expressions.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/expressions.rst b/src/expressions.rst index 62507d7f..f9ebdeea 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5189,47 +5189,47 @@ A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture - :dp:`fls_eNkZWskzznW6` The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`. +:dp:`fls_Vt9C9mKxHOwo` +A :t:`place` is :t:`captured` by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`. + :dp:`fls_v8IFXHJnXhez` -A :t:`place` is not captured when an :t:`underscore expression` is used to bind it. +A :t:`place` is not :t:`captured` when an :t:`underscore expression` is used to bind it. :dp:`fls_gujpU7p5n9Zx` -A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums. +A :t:`place` is not :t:`captured` by destructuring :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. :dp:`fls_t8tFLUg8O83Q` -A :t:`place` is not captured by being matched against a :t:`rest pattern`. +A :t:`place` is not :t:`captured` by being matched against a :t:`rest pattern`. :dp:`fls_RaONmCLH2KGM` -The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing `, or :t:`slicing `. - -:dp:`fls_Vt9C9mKxHOwo` -A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`. +An :t:`array` or :t:`slice` is :t:`captured` whole. :dp:`fls_Fs12dmznjsMf` -Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`. +Matching against an :t:`enum variant` of an :t:`enum` with more than one :t:`[enum variant]s` :t:`captures` the :t:`place` by :t:`immutable borrow`. :dp:`fls_7EXHdE2eOVek` -Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`. +Matching against an :t:`enum variant` of an :t:`enum` with one :t:`enum variant` does not :t:`capture` the :t:`place`, unless it is subject to :t:`attribute` ``non_exhaustive``, in which case the :t:`place` is captured by :t:`immutable borrow`. :dp:`fls_iLH8X2U4ADHb` -Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`. +Matching against a :t:`range pattern` :t:`captures` the :t:`place` by :t:`immutable borrow`. :dp:`fls_HMJUXHrvOmPl` -Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`. +Matching a :t:`slice` against a :t:`slice pattern`, other than one with only a single :t:`rest pattern`, :t:`captures` the :t:`slice` by :t:`immutable borrow`. :dp:`fls_Gj1znNpthHY6` -Matching an array against a slice pattern does not capture the :t:`place`. +Matching an :t:`array` against a :t:`slice pattern` does not :t:`capture` the :t:`place`. :dp:`fls_IFyJvb6mlFU4` -Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. +A :t:`closure expression` subject to keyword ``move`` :t:`captures` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. :dp:`fls_7NEEJgKSpQQ8` -Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. +A :t:`closure expression` :t:`captures` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. :dp:`fls_kYFd3p06pWWV` -Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself. +A :t:`closure expression` :t:`captures` the prefix of a :t:`capture path` of a :t:`union` that runs up to the :t:`union` itself. :dp:`fls_fATMTNUOHsfb` -Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct. +A :t:`closure expression` :t:`captures` the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a :t:`struct` that uses the :t:`attribute` :c:`repr` with modifier ``packed``, in unaligned :t:`[field]s` in a :t:`struct`. :dp:`fls_fITor3jpmgrl` Taking the address of an unaligned :t:`field` captures the entire struct. From 6bbae9bf0ad00900ae9a99723b433d79717331db Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 28 Apr 2026 09:37:22 +0200 Subject: [PATCH 17/26] fix links --- src/expressions.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/expressions.rst b/src/expressions.rst index f9ebdeea..3a28680f 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5205,31 +5205,31 @@ A :t:`place` is not :t:`captured` by being matched against a :t:`rest pattern`. An :t:`array` or :t:`slice` is :t:`captured` whole. :dp:`fls_Fs12dmznjsMf` -Matching against an :t:`enum variant` of an :t:`enum` with more than one :t:`[enum variant]s` :t:`captures` the :t:`place` by :t:`immutable borrow`. +Matching against an :t:`enum variant` of an :t:`enum` with more than one :t:`[enum variant]s` :t:`captures ` the :t:`place` by :t:`immutable borrow`. :dp:`fls_7EXHdE2eOVek` -Matching against an :t:`enum variant` of an :t:`enum` with one :t:`enum variant` does not :t:`capture` the :t:`place`, unless it is subject to :t:`attribute` ``non_exhaustive``, in which case the :t:`place` is captured by :t:`immutable borrow`. +Matching against an :t:`enum variant` of an :t:`enum` with one :t:`enum variant` does not :t:`capture ` the :t:`place`, unless it is subject to :t:`attribute` ``non_exhaustive``, in which case the :t:`place` is captured by :t:`immutable borrow`. :dp:`fls_iLH8X2U4ADHb` -Matching against a :t:`range pattern` :t:`captures` the :t:`place` by :t:`immutable borrow`. +Matching against a :t:`range pattern` :t:`captures ` the :t:`place` by :t:`immutable borrow`. :dp:`fls_HMJUXHrvOmPl` -Matching a :t:`slice` against a :t:`slice pattern`, other than one with only a single :t:`rest pattern`, :t:`captures` the :t:`slice` by :t:`immutable borrow`. +Matching a :t:`slice` against a :t:`slice pattern`, other than one with only a single :t:`rest pattern`, :t:`captures ` the :t:`slice` by :t:`immutable borrow`. :dp:`fls_Gj1znNpthHY6` -Matching an :t:`array` against a :t:`slice pattern` does not :t:`capture` the :t:`place`. +Matching an :t:`array` against a :t:`slice pattern` does not :t:`capture ` the :t:`place`. :dp:`fls_IFyJvb6mlFU4` -A :t:`closure expression` subject to keyword ``move`` :t:`captures` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. +A :t:`closure expression` subject to keyword ``move`` :t:`captures ` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`. :dp:`fls_7NEEJgKSpQQ8` -A :t:`closure expression` :t:`captures` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. +A :t:`closure expression` :t:`captures ` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`. :dp:`fls_kYFd3p06pWWV` -A :t:`closure expression` :t:`captures` the prefix of a :t:`capture path` of a :t:`union` that runs up to the :t:`union` itself. +A :t:`closure expression` :t:`captures ` the prefix of a :t:`capture path` of a :t:`union` that runs up to the :t:`union` itself. :dp:`fls_fATMTNUOHsfb` -A :t:`closure expression` :t:`captures` the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a :t:`struct` that uses the :t:`attribute` :c:`repr` with modifier ``packed``, in unaligned :t:`[field]s` in a :t:`struct`. +A :t:`closure expression` :t:`captures ` the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a :t:`struct` that uses the :t:`attribute` :c:`repr` with modifier ``packed``, in unaligned :t:`[field]s` in a :t:`struct`. :dp:`fls_fITor3jpmgrl` Taking the address of an unaligned :t:`field` captures the entire struct. From fb39a565506dc4ba7a60b08770c3b06263b9820a Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 28 Apr 2026 10:03:18 +0200 Subject: [PATCH 18/26] these should not be conflated --- src/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions.rst b/src/expressions.rst index 3a28680f..c9102a6c 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5193,7 +5193,7 @@ A :t:`closure expression` :t:`[borrow]s` or :t:`moves ` the :t:`capture A :t:`place` is :t:`captured` by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`. :dp:`fls_v8IFXHJnXhez` -A :t:`place` is not :t:`captured` when an :t:`underscore expression` is used to bind it. +A :t:`place` is not :t:`captured` when an :t:`underscore pattern` is used to bind it. :dp:`fls_gujpU7p5n9Zx` A :t:`place` is not :t:`captured` by destructuring :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. From 550f10d2127b8b9329420baaa82d467439544240 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 28 Apr 2026 11:49:07 +0200 Subject: [PATCH 19/26] add some clarity --- src/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions.rst b/src/expressions.rst index c9102a6c..0f4d0943 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5196,7 +5196,7 @@ A :t:`place` is :t:`captured` by :t:`immutable borrow` if its :t:`discriminant` A :t:`place` is not :t:`captured` when an :t:`underscore pattern` is used to bind it. :dp:`fls_gujpU7p5n9Zx` -A :t:`place` is not :t:`captured` by destructuring :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. +A :t:`place` is not :t:`captured` by using a :t:`rest pattern` when destructuring :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. :dp:`fls_t8tFLUg8O83Q` A :t:`place` is not :t:`captured` by being matched against a :t:`rest pattern`. From e66de62b201f7754e85af31e7a37a085601a2d62 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Mon, 4 May 2026 13:08:09 +0200 Subject: [PATCH 20/26] add pattern destructing rules --- src/changelog.rst | 4 ++++ src/expressions.rst | 2 +- src/patterns.rst | 12 ++++++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/src/changelog.rst b/src/changelog.rst index 525fef0f..276ccd33 100644 --- a/src/changelog.rst +++ b/src/changelog.rst @@ -66,6 +66,10 @@ Language changes in Rust 1.95.0 - :p:`fls_kYFd3p06pWWV` - :p:`fls_fATMTNUOHsfb` - :p:`fls_fITor3jpmgrl` + - :p:`fls_UfvoShNTxVD2` + - :p:`fls_wAMHIDvLG0LM` + - :p:`fls_YuQxJCjneaW5` + - :p:`fls_nrTZ4mn6IJCl` FLS corrections --------------- diff --git a/src/expressions.rst b/src/expressions.rst index 0f4d0943..521afc3e 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5175,7 +5175,7 @@ Capture precision ~~~~~~~~~~~~~~~~~ :dp:`fls_j9WyKVyOLFon` -A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`. +A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern destructuring` applied to a :t:`variable`. :dp:`fls_rdDT7jsaOMbs` A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`. diff --git a/src/patterns.rst b/src/patterns.rst index 6d2de0b6..0e62a3d5 100644 --- a/src/patterns.rst +++ b/src/patterns.rst @@ -90,6 +90,18 @@ restrictions: Any two :t:`[binding]s` with the same name in the two :t:`[pattern-without-alternation]s` shall have :t:`[unifiable type]s` and shall have the same :t:`[binding mode]s`. +:dp:`fls_UfvoShNTxVD2` +:dt:`Pattern destructuring` is where :t:`[value]s` of :t:`[struct]s`, :t:`[enum]s`, and :t:`[tuple]s` are broken into :t:`[struct field]s`, :t:`[enum variant]s`, and :t:`[tuple field]s`, respectively. + +:dp:`fls_wAMHIDvLG0LM` +In a pattern whose :t:`subject expression` is a :t:`struct type`, an :t:`underscore pattern` matches a single :t:`struct field`, and a :t:`rest pattern` matches the remaining fields. + +:dp:`fls_YuQxJCjneaW5` +In a pattern whose :t:`subject expression` is an :t:`enum type`, an :t:`underscore pattern` matches a single :t:`enum variant`, and a :t:`rest pattern` matches the remaining variants. + +:dp:`fls_nrTZ4mn6IJCl` +In a pattern whose :t:`subject expression` is a :t:`tuple type`, an :t:`underscore pattern` matches a single :t:`tuple field`, and a :t:`rest pattern` matches the remaining fields. + .. _fls_uh76pw6ykd57: Refutability From a0f78bc4f7e57a666706de332f8079ba9ab484ab Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 5 May 2026 12:16:21 +0200 Subject: [PATCH 21/26] clarity Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions.rst b/src/expressions.rst index 521afc3e..fa770e30 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5208,7 +5208,7 @@ An :t:`array` or :t:`slice` is :t:`captured` whole. Matching against an :t:`enum variant` of an :t:`enum` with more than one :t:`[enum variant]s` :t:`captures ` the :t:`place` by :t:`immutable borrow`. :dp:`fls_7EXHdE2eOVek` -Matching against an :t:`enum variant` of an :t:`enum` with one :t:`enum variant` does not :t:`capture ` the :t:`place`, unless it is subject to :t:`attribute` ``non_exhaustive``, in which case the :t:`place` is captured by :t:`immutable borrow`. +Matching against an :t:`enum variant` of an :t:`enum` with one :t:`enum variant` does not :t:`capture ` the :t:`place`, unless the :t:`enum` is subject to :t:`attribute` ``non_exhaustive``, in which case the :t:`place` is captured by :t:`immutable borrow`. :dp:`fls_iLH8X2U4ADHb` Matching against a :t:`range pattern` :t:`captures ` the :t:`place` by :t:`immutable borrow`. From 3279af39e503ed780c045935752e604281dbeeec Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 5 May 2026 14:25:09 +0200 Subject: [PATCH 22/26] sort Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/patterns.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/patterns.rst b/src/patterns.rst index 0e62a3d5..1316af64 100644 --- a/src/patterns.rst +++ b/src/patterns.rst @@ -91,7 +91,7 @@ restrictions: :t:`[unifiable type]s` and shall have the same :t:`[binding mode]s`. :dp:`fls_UfvoShNTxVD2` -:dt:`Pattern destructuring` is where :t:`[value]s` of :t:`[struct]s`, :t:`[enum]s`, and :t:`[tuple]s` are broken into :t:`[struct field]s`, :t:`[enum variant]s`, and :t:`[tuple field]s`, respectively. +:dt:`Pattern destructuring` is where :t:`[value]s` of :t:`[enum]s`, :t:`[struct]s`, and :t:`[tuple]s` are broken into :t:`[enum variant]s`, :t:`[struct field]s`, and :t:`[tuple field]s`, respectively. :dp:`fls_wAMHIDvLG0LM` In a pattern whose :t:`subject expression` is a :t:`struct type`, an :t:`underscore pattern` matches a single :t:`struct field`, and a :t:`rest pattern` matches the remaining fields. From 805394629ef29644f2108c836d67d9adc1193df0 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 5 May 2026 14:30:03 +0200 Subject: [PATCH 23/26] more sorting Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com> --- src/patterns.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/patterns.rst b/src/patterns.rst index 1316af64..98711a52 100644 --- a/src/patterns.rst +++ b/src/patterns.rst @@ -93,15 +93,14 @@ restrictions: :dp:`fls_UfvoShNTxVD2` :dt:`Pattern destructuring` is where :t:`[value]s` of :t:`[enum]s`, :t:`[struct]s`, and :t:`[tuple]s` are broken into :t:`[enum variant]s`, :t:`[struct field]s`, and :t:`[tuple field]s`, respectively. -:dp:`fls_wAMHIDvLG0LM` -In a pattern whose :t:`subject expression` is a :t:`struct type`, an :t:`underscore pattern` matches a single :t:`struct field`, and a :t:`rest pattern` matches the remaining fields. - :dp:`fls_YuQxJCjneaW5` In a pattern whose :t:`subject expression` is an :t:`enum type`, an :t:`underscore pattern` matches a single :t:`enum variant`, and a :t:`rest pattern` matches the remaining variants. +:dp:`fls_wAMHIDvLG0LM` +In a pattern whose :t:`subject expression` is a :t:`struct type`, an :t:`underscore pattern` matches a single :t:`struct field`, and a :t:`rest pattern` matches the remaining fields. + :dp:`fls_nrTZ4mn6IJCl` In a pattern whose :t:`subject expression` is a :t:`tuple type`, an :t:`underscore pattern` matches a single :t:`tuple field`, and a :t:`rest pattern` matches the remaining fields. - .. _fls_uh76pw6ykd57: Refutability From 3056e1f3784b579b01e901b1b765e8e396021ac5 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 5 May 2026 14:47:27 +0200 Subject: [PATCH 24/26] create section for pattern destructuring --- src/changelog.rst | 2 ++ src/patterns.rst | 28 +++++++++++++++++----------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/src/changelog.rst b/src/changelog.rst index 276ccd33..a329e723 100644 --- a/src/changelog.rst +++ b/src/changelog.rst @@ -44,6 +44,8 @@ Language changes in Rust 1.95.0 - :p:`fls_33hfay24hx8u` - :p:`fls_uqy5w9uc8gla` + New section, which documents functionality that existed well before this release: :ref:`fls_buRbhu22Gfdu` + New paragraphs, which mostly document behavior that existed before this release: - :p:`fls_rdDT7jsaOMbs` diff --git a/src/patterns.rst b/src/patterns.rst index 98711a52..6f78a414 100644 --- a/src/patterns.rst +++ b/src/patterns.rst @@ -90,17 +90,6 @@ restrictions: Any two :t:`[binding]s` with the same name in the two :t:`[pattern-without-alternation]s` shall have :t:`[unifiable type]s` and shall have the same :t:`[binding mode]s`. -:dp:`fls_UfvoShNTxVD2` -:dt:`Pattern destructuring` is where :t:`[value]s` of :t:`[enum]s`, :t:`[struct]s`, and :t:`[tuple]s` are broken into :t:`[enum variant]s`, :t:`[struct field]s`, and :t:`[tuple field]s`, respectively. - -:dp:`fls_YuQxJCjneaW5` -In a pattern whose :t:`subject expression` is an :t:`enum type`, an :t:`underscore pattern` matches a single :t:`enum variant`, and a :t:`rest pattern` matches the remaining variants. - -:dp:`fls_wAMHIDvLG0LM` -In a pattern whose :t:`subject expression` is a :t:`struct type`, an :t:`underscore pattern` matches a single :t:`struct field`, and a :t:`rest pattern` matches the remaining fields. - -:dp:`fls_nrTZ4mn6IJCl` -In a pattern whose :t:`subject expression` is a :t:`tuple type`, an :t:`underscore pattern` matches a single :t:`tuple field`, and a :t:`rest pattern` matches the remaining fields. .. _fls_uh76pw6ykd57: Refutability @@ -147,6 +136,23 @@ A :t:`refutable constant` is a :t:`constant` of a :t:`refutable type`. if let core::option::Option::Some(y) = value { +.. _fls_buRbhu22Gfdu: + +Pattern Destructuring +--------------------- + +:dp:`fls_UfvoShNTxVD2` +:dt:`Pattern destructuring` is where :t:`[value]s` of :t:`[enum]s`, :t:`[struct]s`, and :t:`[tuple]s` are broken into :t:`[enum variant]s`, :t:`[struct field]s`, and :t:`[tuple field]s`, respectively. + +:dp:`fls_YuQxJCjneaW5` +In a pattern whose :t:`subject expression` is an :t:`enum type`, an :t:`underscore pattern` matches a single :t:`enum variant`, and a :t:`rest pattern` matches the remaining variants. + +:dp:`fls_wAMHIDvLG0LM` +In a pattern whose :t:`subject expression` is a :t:`struct type`, an :t:`underscore pattern` matches a single :t:`struct field`, and a :t:`rest pattern` matches the remaining fields. + +:dp:`fls_nrTZ4mn6IJCl` +In a pattern whose :t:`subject expression` is a :t:`tuple type`, an :t:`underscore pattern` matches a single :t:`tuple field`, and a :t:`rest pattern` matches the remaining fields. + .. _fls_7bxv8lybxm18: Identifier Patterns From 03503ca4d5c145529e657cd4b3d8845c9677fea6 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 5 May 2026 15:39:13 +0200 Subject: [PATCH 25/26] link-it --- src/expressions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/expressions.rst b/src/expressions.rst index fa770e30..18044707 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5196,7 +5196,7 @@ A :t:`place` is :t:`captured` by :t:`immutable borrow` if its :t:`discriminant` A :t:`place` is not :t:`captured` when an :t:`underscore pattern` is used to bind it. :dp:`fls_gujpU7p5n9Zx` -A :t:`place` is not :t:`captured` by using a :t:`rest pattern` when destructuring :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. +A :t:`place` is not :t:`captured` by using a :t:`rest pattern` when :t:`destructuring ` :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. :dp:`fls_t8tFLUg8O83Q` A :t:`place` is not :t:`captured` by being matched against a :t:`rest pattern`. @@ -5232,7 +5232,7 @@ A :t:`closure expression` :t:`captures ` the prefix of a :t:`capture A :t:`closure expression` :t:`captures ` the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a :t:`struct` that uses the :t:`attribute` :c:`repr` with modifier ``packed``, in unaligned :t:`[field]s` in a :t:`struct`. :dp:`fls_fITor3jpmgrl` -Taking the address of an unaligned :t:`field` captures the entire struct. +Taking the address of an unaligned :t:`field` :t:`captures ` the entire :t:`struct`. .. _fls_ZfIBiJMf8qE1: From 7713de9b49a58a1234c2b10832fc96bdc08ec0eb Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 5 May 2026 15:43:07 +0200 Subject: [PATCH 26/26] fix --- src/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions.rst b/src/expressions.rst index 18044707..01a11345 100644 --- a/src/expressions.rst +++ b/src/expressions.rst @@ -5199,7 +5199,7 @@ A :t:`place` is not :t:`captured` when an :t:`underscore pattern` is used to bin A :t:`place` is not :t:`captured` by using a :t:`rest pattern` when :t:`destructuring ` :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`. :dp:`fls_t8tFLUg8O83Q` -A :t:`place` is not :t:`captured` by being matched against a :t:`rest pattern`. +A :t:`field` is not :t:`captured` by being matched against a :t:`rest pattern`. :dp:`fls_RaONmCLH2KGM` An :t:`array` or :t:`slice` is :t:`captured` whole.