|
| 1 | +.. SPDX-License-Identifier: MIT OR Apache-2.0 |
| 2 | + SPDX-FileCopyrightText: The Ferrocene Developers |
| 3 | +
|
| 4 | +.. default-domain:: spec |
| 5 | + |
| 6 | +.. _fls_l21tjqjkkaa0: |
| 7 | + |
| 8 | +Associated Items |
| 9 | +================ |
| 10 | + |
| 11 | +.. rubric:: Syntax |
| 12 | + |
| 13 | +.. syntax:: |
| 14 | + |
| 15 | + AssociatedItem ::= |
| 16 | + OuterAttributeOrDoc* (AssociatedItemWithVisibility | TerminatedMacroInvocation) |
| 17 | + |
| 18 | + AssociatedItemWithVisibility ::= |
| 19 | + VisibilityModifier? ( |
| 20 | + ConstantDeclaration |
| 21 | + | FunctionDeclaration |
| 22 | + | TypeAliasDeclaration |
| 23 | + ) |
| 24 | + |
| 25 | +.. rubric:: Legality Rules |
| 26 | + |
| 27 | +:dp:`fls_ckzd25qd213t` |
| 28 | +An :t:`associated item` is an :t:`item` that appears within an |
| 29 | +:t:`implementation` or a :t:`trait`. |
| 30 | + |
| 31 | +:dp:`fls_5y6ae0xqux57` |
| 32 | +An :t:`associated constant` is a :t:`constant` that appears as an |
| 33 | +:t:`associated item`. |
| 34 | + |
| 35 | +:dp:`fls_lj7492aq7fzo` |
| 36 | +An :t:`associated function` is a :t:`function` that appears as an |
| 37 | +:t:`associated item`. |
| 38 | + |
| 39 | +:dp:`fls_8cz4rdrklaj4` |
| 40 | +An :t:`associated type` is a :t:`type alias` that appears as an |
| 41 | +:t:`associated item`. |
| 42 | + |
| 43 | +:dp:`fls_w8nu8suy7t5` |
| 44 | +An :t:`associated type` shall not be used in the :t:`path expression` of a |
| 45 | +:t:`struct expression`. |
| 46 | + |
| 47 | +:dp:`fls_wasocqdnuzd1` |
| 48 | +An :t:`associated type` with a :s:`TypeBoundList` shall appear only as an |
| 49 | +:t:`associated trait type`. |
| 50 | + |
| 51 | +:dp:`fls_PeD0DzjK57be` |
| 52 | +A :t:`generic associated type` is an :t:`associated type` with |
| 53 | +:t:`[generic parameter]s`. |
| 54 | + |
| 55 | +:dp:`fls_3foYUch29ZtF` |
| 56 | +A :t:`lifetime parameter` of a :t:`generic associated type` requires a |
| 57 | +:t:`bound` of the form ``T: 'lifetime``, where ``T`` is a :t:`type parameter` |
| 58 | +or :c:`Self` and ``'lifetime`` is the :t:`lifetime parameter`, when |
| 59 | + |
| 60 | +* :dp:`fls_SnQc0zZS57Cz` |
| 61 | + The :t:`generic associated type` is used in an :t:`associated function` of |
| 62 | + the same :t:`trait`, and |
| 63 | + |
| 64 | +* :dp:`fls_6Z05BK2JSzpP` |
| 65 | + The corresponding :t:`lifetime argument` in the use is not the ``'static`` |
| 66 | + :t:`lifetime` and has either an explicit :t:`bound` or an :t:`implicit bound` |
| 67 | + that constrains the :t:`type parameter`, and |
| 68 | + |
| 69 | +* :dp:`fls_AtItgS1UvwiX` |
| 70 | + The intersection of all such uses is not empty. |
| 71 | + |
| 72 | +:dp:`fls_l3iwn56n1uz8` |
| 73 | +An :t:`associated implementation constant` is an :t:`associated constant` that |
| 74 | +appears within an :t:`implementation`. |
| 75 | + |
| 76 | +:dp:`fls_4ftfefcotb4g` |
| 77 | +An :t:`associated implementation constant` shall have a :t:`constant |
| 78 | +initializer`. |
| 79 | + |
| 80 | +:dp:`fls_qb5qpfe0uwk` |
| 81 | +An :t:`associated implementation function` is an :t:`associated function` that |
| 82 | +appears within an :t:`implementation`. |
| 83 | + |
| 84 | +:dp:`fls_1zlkeb6fz10j` |
| 85 | +An :t:`associated implementation function` shall have a :t:`function body`. |
| 86 | + |
| 87 | +:dp:`fls_tw8u0cc5867l` |
| 88 | +An :t:`associated implementation type` is an :t:`associated type` that appears |
| 89 | +within an :t:`implementation`. |
| 90 | + |
| 91 | +:dp:`fls_bx7931x4155h` |
| 92 | +An :t:`associated implementation type` shall have an :t:`initialization type`. |
| 93 | + |
| 94 | +:dp:`fls_bnTcCbDvdp94` |
| 95 | +An :t:`associated trait item` is an :t:`associated item` that appears |
| 96 | +within a :t:`trait`. |
| 97 | + |
| 98 | +:dp:`fls_N3cdn4lCZ2Bf` |
| 99 | +An :t:`associated trait implementation item` is an :t:`associated item` that |
| 100 | +appears within a :t:`trait implementation`. |
| 101 | + |
| 102 | +:dp:`fls_x564isbhobym` |
| 103 | +An :t:`associated trait constant` is an :t:`associated constant` that appears |
| 104 | +within a :t:`trait`. |
| 105 | + |
| 106 | +:dp:`fls_b6nns7oqvdpm` |
| 107 | +An :t:`associated trait function` is an :t:`associated function` that appears |
| 108 | +within a :t:`trait`. |
| 109 | + |
| 110 | +:dp:`fls_2TRwCz38kuRz` |
| 111 | +An :t:`associated trait function` shall not be subject to :t:`keyword` ``const``. |
| 112 | + |
| 113 | +:dp:`fls_WnsVATJvUdza` |
| 114 | +Every occurrence of an :t:`impl trait type` in the :t:`return type` of an |
| 115 | +:t:`associated trait function` is equivalent to referring to a new |
| 116 | +anonymous :t:`associated trait type` of the :t:`implemented trait`. |
| 117 | + |
| 118 | +:dp:`fls_yyhebj4qyk34` |
| 119 | +An :t:`associated trait type` is an :t:`associated type` that appears within |
| 120 | +a :t:`trait`. |
| 121 | + |
| 122 | +:dp:`fls_kl9p3ycl5mzf` |
| 123 | +An :t:`associated trait type` shall not have an :t:`initialization type`. |
| 124 | + |
| 125 | +:dp:`fls_a5prbmuruma4` |
| 126 | +An :t:`associated trait type` has an implicit :std:`core::marker::Sized` |
| 127 | +:t:`bound`. |
| 128 | + |
| 129 | +:dp:`fls_vp2ov6ykueue` |
| 130 | +An :t:`associated trait type` of the form |
| 131 | + |
| 132 | +.. code-block:: rust |
| 133 | +
|
| 134 | + trait T { |
| 135 | + type X: Bound; |
| 136 | + } |
| 137 | +
|
| 138 | +:dp:`fls_5uf74nvdm64o` |
| 139 | +is equivalent to a :t:`where clause` of the following form: |
| 140 | + |
| 141 | +.. code-block:: rust |
| 142 | +
|
| 143 | + trait T where Self::X: Bound { |
| 144 | + type X; |
| 145 | + } |
| 146 | +
|
| 147 | +:dp:`fls_amWtS80fPtza` |
| 148 | +An :t:`associated trait implementation function` is an :t:`associated function` |
| 149 | +that appears within a :t:`trait implementation`. |
| 150 | + |
| 151 | +:dp:`fls_Cu8FWrisrqz1` |
| 152 | +Every occurrence of an :t:`impl trait type` in the :t:`return type` of an |
| 153 | +:t:`associated trait implementation function` is equivalent to referring to the |
| 154 | +corresponding :t:`associated trait type` of the corresponding :t:`associated |
| 155 | +trait function`. |
| 156 | + |
| 157 | +:dp:`fls_oy92gzxgc273` |
| 158 | +A :t:`method` is an :t:`associated function` with a :t:`self parameter`. |
| 159 | + |
| 160 | +:dp:`fls_WXnCWfJGoQx3` |
| 161 | +The type of a :t:`self parameter` shall be one of the following: |
| 162 | + |
| 163 | +* :dp:`fls_OaszUw4IFobz` |
| 164 | + A :t:`type specification` resolving to the :t:`implementing type` of the |
| 165 | + related :t:`implementation`, or |
| 166 | + |
| 167 | +* :dp:`fls_Wd2FZRomB5yn` |
| 168 | + ``&T`` where ``T`` is one of the :t:`[type]s` listed in this enumeration, |
| 169 | + or |
| 170 | + |
| 171 | +* :dp:`fls_lcEyToYIlcmf` |
| 172 | + ``&mut T`` where ``T`` is one of the :t:`[type]s` listed in this |
| 173 | + enumeration, or |
| 174 | + |
| 175 | +* :dp:`fls_IKSPR7ZQMErU` |
| 176 | + :std:`core::pin::Pin<T> <core::pin::Pin>` where ``T`` is one of the the :t:`[type]s` listed in this |
| 177 | + enumeration. |
| 178 | + |
| 179 | +:dp:`fls_oHxzyaiT7Qm6` |
| 180 | +The :t:`visibility modifier` of an :t:`associated trait item` or :t:`associated |
| 181 | +trait implementation item` is rejected, but may still be consumed by |
| 182 | +:t:`[macro]s`. |
| 183 | + |
| 184 | +.. rubric:: Examples |
| 185 | + |
| 186 | +.. code-block:: rust |
| 187 | +
|
| 188 | + trait Greeter { |
| 189 | + const MAX_GREETINGS: i32; |
| 190 | +
|
| 191 | + fn greet(self, message: &str); |
| 192 | + } |
| 193 | +
|
| 194 | + struct Implementor { |
| 195 | + delivered_greetings: i32 |
| 196 | + } |
| 197 | +
|
| 198 | + impl Greeter for Implementor { |
| 199 | + const MAX_GREETINGS: i32 = 42; |
| 200 | +
|
| 201 | + fn greet(mut self, message: &str) { |
| 202 | + if self.delivered_greetings < Self::MAX_GREETINGS { |
| 203 | + self.delivered_greetings += 1; |
| 204 | + println!("{}", message); |
| 205 | + } |
| 206 | + } |
| 207 | + } |
| 208 | +
|
| 209 | +:dp:`fls_znfADVeOvXHD` |
| 210 | +Generic associated type with lifetime bound. |
| 211 | + |
| 212 | +.. code-block:: rust |
| 213 | +
|
| 214 | + trait LendingIterator { |
| 215 | + type Item<'x> where Self: 'x; |
| 216 | +
|
| 217 | + fn next<'a>(&'a mut self) -> Self::Item<'a>; |
| 218 | + } |
0 commit comments