feat: add first draft of drop order in or patterns clarification

src/glossary.rst

@@ -3741,6 +3741,15 @@ tests for a less-than-or-equals relationship.
 :dp:`fls_ft5aeo4ilgwc`
 See :s:`LessThanOrEqualsExpression`.
 
+
+.. _fls_DdZ1ZwjLZTeG:
+
+let binding
+^^^^^^^^^^^
+
+:dp:`fls_sw6HrsxsnG2y`
+A :dt:`let binding` is the :t:`binding` introduced by a :t:`let statement`, an :t:`if let expression`, or a :t:`while let loop expression`.
+
 .. _fls_hqj80jHcxEBB:
 
 let initializer
@@ -4713,6 +4722,18 @@ opt-out trait bound
 An :dt:`opt-out trait bound` is a :t:`trait bound` with :s:`Punctuation` ``?``
 that nullifies an implicitly added :t:`trait bound`.
 
+
+.. _fls_LnPDQW3bnNUw:
+
+or-pattern
+^^^^^^^^^^
+
+:dp:`fls_LnPDQW3bnNUw`
+An :dt:`or-pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s them using character 0x7C (vertical line, i.e. ``|``).
+
+:dp:`fls_urIJ5JNHLhm6`
+See :s:`Pattern`.
+
 .. _fls_gllzixm9yt9w:
 
 outer attribute
@@ -4969,8 +4990,7 @@ pattern matching
 ^^^^^^^^^^^^^^^^
 
 :dp:`fls_y3oputy9e0sz`
-:dt:`Pattern matching` is the process of matching a :t:`pattern` against a
-:t:`value`.
+:t:`Pattern matching` is the process of matching a :t:`pattern` against a :t:`value`.
 
 .. _fls_cptagvgpgnze:
 

src/ownership-and-deconstruction.rst

@@ -694,12 +694,17 @@ Drop Order
 When a :t:`drop scope` is left, all :t:`[value]s` associated with that
 :t:`drop scope` are :t:`dropped` as follows:
 
-* :dp:`fls_g07zq3n55094`
-  :t:`[Binding]s` are :t:`dropped` in reverse declaration order.
+* :dp:`fls_W2S2FrkuedYC`
+  :t:`[Binding]s` introduced by an :t:`or-pattern` are dropped in reverse
+  declaration order, where the declaration order is defined by the first
+  :t:`pattern-without-alternation`.
 
 * :dp:`fls_a5tmilqxdb6f`
   :t:`Temporaries <temporary>` are :t:`dropped` in reverse creation order.
 
+* :dp:`fls_g07zq3n55094`
+  All other :t:`bindings` are :t:`dropped` in reverse declaration order.
+
 :dp:`fls_zQGkVGWIzMQ7`
 When a :t:`drop scope` of a :t:`function` is left, then each
 :t:`function parameter` is :t:`dropped` from right to left as follows:
@@ -748,3 +753,24 @@ proceeds as follows:
    }
    let c = PrintOnDrop("2");
 
+:dp:`fls_dhfIPP4yR3Tt`
+In the following example, the drop order is ``b``, ``a`` for both calls.
+Dropping proceeds as follows:
+
+#. :dp:`fls_zxFM7EoE2Xq8`
+   The first :t:`pattern-without-alternation` ``Ok([a, b])`` declares ``a`` before ``b``.
+
+#. :dp:`fls_093YxG6YXQz2`
+   When the first call matches ``Ok([a, b])``, the :t:`[binding]s` are dropped in reverse declaration order: ``b`` then ``a``.
+
+#. :dp:`fls_gNWXh61ZXXt8`
+   When the second call matches ``Err([b, a])``, the drop order remains ``b`` then ``a`` since it is determined by the first :t:`pattern-without-alternation`.
+
+.. code-block:: rust
+
+   fn drop_order<T>((Ok([a, b]) | Err([b, a])): Result<[T; 2], [T; 2]>) {}
+
+   drop_order(Ok([PrintOnDrop("1"), PrintOnDrop("2")]));
+
+   drop_order(Err([PrintOnDrop("2"), PrintOnDrop("1")]));
+

src/patterns.rst

@@ -41,6 +41,9 @@ Patterns
 A :t:`pattern` is a :t:`construct` that matches a :t:`value` which satisfies all
 the criteria of the :t:`pattern`.
 
+:dp:`fls_VQMmveZUfNTn`
+An :t:`or-pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s them using character 0x7C (vertical line).
+
 :dp:`fls_mp6i4blzexnu`
 A :t:`pattern-without-alternation` is a :t:`pattern` that cannot be alternated.
 
@@ -65,18 +68,24 @@ of a :t:`pattern-without-range`, except for when the :t:`pattern` is ``&mut``
 :s:`Identifier`. Such a :t:`pattern` is interpreted as a :t:`reference pattern`
 with :t:`keyword` ``mut`` containing an :t:`identifier pattern`.
 
+:dp:`fls_72JHo343O7jp`
+An or-pattern shall not appear in the :t:`pattern-without-alternation` of a
+:t:`closure parameter`, a :t:`function parameter`, or a :t:`let binding`.
+
 :dp:`fls_8luyomzppck`
-Any two :t:`[pattern-without-alternation]s` that are or-ed using character 0x7C
-(vertical line) are subject to the following restrictions:
+Any two :t:`[subpattern]s` of an :t:`or-pattern` are subject to the following
+restrictions:
 
 * :dp:`fls_rpvdfmy3n05a`
   The :t:`[type]s` of the two :t:`[pattern-without-alternation]s` shall be
   :t:`unifiable`.
 
+* :dp:`fls_YDVgFaTQwcL8`
+  The set of :t:`[binding]s` introduced by the two :t:`[pattern-without-alternation]s` shall be the same.
+
 * :dp:`fls_kv533rntni1x`
-  The :t:`[binding]s` of the two :t:`[pattern-without-alternation]s` shall
-  be the same, shall have :t:`[unifiable type]s`, and shall have the same
-  :t:`[binding mode]s`.
+  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`.
 
 .. _fls_uh76pw6ykd57:
 
@@ -1290,64 +1299,57 @@ follows:
 Pattern Matching
 ----------------
 
+:dp:`fls_zv73CR8rplIa`
+:dt:`Pattern matching` is the process of matching a :t:`pattern` against a :t:`value`.
+
 .. rubric:: Legality Rules
 
 :dp:`fls_tlwr4u7bjhh5`
 :t:`Pattern matching` that involves a :t:`pattern` and a context :t:`value`
 proceeds as follows:
 
-#. :dp:`fls_67ajub7d2b4c`
-   For each :t:`pattern-without-alternation` of the :t:`pattern`:
+#. :dp:`fls_tZJgZDWVChJV`
+   If the :t:`pattern` is an :t:`or-pattern`, then perform :t:`pattern matching` with each :t:`pattern-without-alternation` of the :t:`or-pattern` and the :t:`value`. If any such :t:`pattern matching` succeeds, then the overall :t:`pattern matching` succeeds.
+
+#. :dp:`fls_62626ws222op`
+   If the :t:`pattern` is an :t:`identifier pattern`, then perform :t:`identifier pattern matching`.
 
-   #. :dp:`fls_62626ws222op`
-      If the :t:`pattern-without-alternation` is an :t:`identifier pattern`,
-      then perform :t:`identifier pattern matching`.
+#. :dp:`fls_q0z46h1gnzez`
+   If the :t:`pattern` is a :t:`literal pattern`, then perform :t:`literal pattern matching`.
 
-   #. :dp:`fls_q0z46h1gnzez`
-      If the :t:`pattern-without-alternation` is a :t:`literal pattern`, then
-      perform :t:`literal pattern matching`.
 
-   #. :dp:`fls_1r0vm6rg13o9`
-      If the :t:`pattern-without-alternation` is a :t:`parenthesized pattern`,
-      then perform :t:`parenthesized pattern matching`.
+#. :dp:`fls_1r0vm6rg13o9`
+   If the :t:`pattern` is a :t:`parenthesized pattern`, then perform :t:`parenthesized pattern matching`.
 
-   #. :dp:`fls_am5h8r887bz5`
-      If the :t:`pattern-without-alternation` is a :t:`path pattern`, then
-      perform :t:`path pattern matching`.
+#. :dp:`fls_am5h8r887bz5`
+   If the :t:`pattern` is a :t:`path pattern`, then perform :t:`path pattern matching`.
 
-   #. :dp:`fls_eppmiloh7bgg`
-      If the :t:`pattern-without-alternation` is a :t:`range pattern`, then
-      perform :t:`range pattern matching`.
+#. :dp:`fls_eppmiloh7bgg`
+   If the :t:`pattern` is a :t:`range pattern`, then perform :t:`range pattern matching`.
 
-   #. :dp:`fls_gwc08xayno7q`
-      If the :t:`pattern-without-alternation` is a :t:`reference pattern`, then
-      perform :t:`reference pattern matching`.
+#. :dp:`fls_gwc08xayno7q`
+   If the :t:`pattern` is a :t:`reference pattern`, then perform :t:`reference pattern matching`.
 
-   #. :dp:`fls_19iygu12s315`
-      If the :t:`pattern-without-alternation` is a :t:`slice pattern`, then
-      perform :t:`slice pattern matching`.
+#. :dp:`fls_19iygu12s315`
+   If the :t:`pattern` is a :t:`slice pattern`, then perform :t:`slice pattern matching`.
 
-   #. :dp:`fls_r307spfk6cs9`
-      If the :t:`pattern-without-alternation` is a :t:`record struct pattern`,
-      then perform :t:`record struct pattern matching`.
+#. :dp:`fls_r307spfk6cs9`
+   If the :t:`pattern` is a :t:`record struct pattern`, then perform :t:`record struct pattern matching`.
 
-   #. :dp:`fls_qhdofvbso3gl`
-      If the :t:`pattern-without-alternation` is a :t:`tuple struct pattern`,
-      then perform :t:`tuple struct pattern matching`.
+#. :dp:`fls_qhdofvbso3gl`
+   If the :t:`pattern` is a :t:`tuple struct pattern`, then perform :t:`tuple struct pattern matching`.
 
-   #. :dp:`fls_drb114dtvlpt`
-      If the :t:`pattern-without-alternation` is a :t:`tuple pattern`, then
-      perform :t:`tuple pattern matching`.
+#. :dp:`fls_drb114dtvlpt`
+   If the :t:`pattern` is a :t:`tuple pattern`, then perform :t:`tuple pattern matching`.
 
-   #. :dp:`fls_uxysntb3u03j`
-      If the :t:`pattern-without-alternation` is an :t:`underscore pattern`,
-      then perform :t:`underscore pattern matching`.
+#. :dp:`fls_uxysntb3u03j`
+   If the :t:`pattern` is an :t:`underscore pattern`, then perform :t:`underscore pattern matching`.
 
-   #. :dp:`fls_wh201rmh6u6d`
-      Otherwise :t:`pattern matching` fails.
+#. :dp:`fls_wh201rmh6u6d`
+   Otherwise :t:`pattern matching` fails.
 
 :dp:`fls_vstdqifqipbh`
-Only the :t:`[binding]s` of a matched :t:`pattern-without-alternation` are
+Only the :t:`[binding]s` of the matched :t:`pattern` are
 introduced into a :t:`binding scope`.
 
 .. _fls_vnai6ag4qrdb: