Skip to content

Commit ac6a74f

Browse files
matthewjaspermatthewjasper
authored
Merge pull request #430 from ehuss/grammar-fn-stuff
Grammar: Functions, methods, impl, traits, extern.
2 parents 9214ce6 + 028fd75 commit ac6a74f

File tree

6 files changed

+260
-14
lines changed

6 files changed

+260
-14
lines changed

‎src/items/associated-items.md

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,17 +79,31 @@ let _: f64 = f64::from_i32(42);
7979

8080
### Methods
8181

82+
> _Method_ :\
83+
> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
84+
> &nbsp;&nbsp; &nbsp;&nbsp; `(` _SelfParam_ (`,` [_FunctionParam_])<sup>\*</sup> `,`<sup>?</sup> `)`\
85+
> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>\
86+
> &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
87+
>
88+
> _SelfParam_ :\
89+
> &nbsp;&nbsp; &nbsp;&nbsp; (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`\
90+
> &nbsp;&nbsp; | `mut`<sup>?</sup> `self` (`:` [_Type_])<sup>?</sup>
91+
8292
Associated functions whose first parameter is named `self` are called *methods*
8393
and may be invoked using the [method call operator], for example, `x.foo()`, as
8494
well as the usual function call notation.
8595

86-
The `self` parameter must have one of the following types. As a result, the
87-
following shorthands may be used to declare `self`:
96+
If the type of the `self` parameter is specified, it is limited to the type
97+
being implemented (or `Self`), or a reference or mutable reference to the
98+
type, or a boxed value of the type being implemented (such as `Box<Self>`).
99+
Shorthand syntax can be used without specifying a type, which have the
100+
following equivalents:
88101

89-
* `self` -> `self: Self`
90-
* `&'lifetime self` -> `self: &'lifetime Self`
91-
* `&'lifetime mut self` -> `self: &'lifetime mut Self`
92-
* `self : Box<Self>` (no shorthand)
102+
Shorthand | Equivalent
103+
----------------------|-----------
104+
`self` | `self: Self`
105+
`&'lifetime self` | `self: &'lifetime Self`
106+
`&'lifetime mut self` | `self: &'lifetime mut Self`
93107

94108
> Note: Lifetimes can be and usually are elided with this shorthand.
95109
@@ -272,6 +286,14 @@ fn main() {
272286
}
273287
```
274288

289+
[_BlockExpression_]: expressions/block-expr.html
290+
[_FunctionFront_]: items/functions.html
291+
[_FunctionParam_]: items/functions.html
292+
[_FunctionReturnType_]: items/functions.html
293+
[_Generics_]: items/generics.html
294+
[_Lifetime_]: trait-bounds.html
295+
[_Type_]: types.html
296+
[_WhereClause_]: items/generics.html#where-clauses
275297
[trait]: items/traits.html
276298
[traits]: items/traits.html
277299
[type aliases]: items/type-aliases.html

‎src/items/external-blocks.md

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,42 @@
11
# External blocks
22

3+
> **<sup>Syntax</sup>**\
4+
> _ExternBlock_ :\
5+
> &nbsp;&nbsp; `extern` [_Abi_]<sup>?</sup> `{`\
6+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
7+
> &nbsp;&nbsp; &nbsp;&nbsp; _ExternalItem_<sup>\*</sup>\
8+
> &nbsp;&nbsp; `}`
9+
>
10+
> _ExternalItem_ :\
11+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
12+
> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
13+
> &nbsp;&nbsp; ( _ExternalStaticItem_ | _ExternalFunctionItem_ )
14+
>
15+
> _ExternalStaticItem_ :\
16+
> &nbsp;&nbsp; `static` `mut`<sup>?</sup> [IDENTIFIER] `:` [_Type_] `;`
17+
>
18+
> _ExternalFunctionItem_ :\
19+
> &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
20+
> &nbsp;&nbsp; `(` _NamedFunctionParameters_<sup>?</sup> | _NamedFunctionParametersWithVariadics_ ) `)`\
21+
> &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup> `;`
22+
>
23+
> _NamedFunctionParameters_ :\
24+
> &nbsp;&nbsp; _NamedFunctionParam_ ( `,` _NamedFunctionParam_ )<sup>\*</sup> `,`<sup>?</sup>
25+
>
26+
> _NamedFunctionParam_ :\
27+
> &nbsp;&nbsp; ( [IDENTIFIER] | `_` ) `:` [_Type_]
28+
>
29+
> _NamedFunctionParametersWithVariadics_ :\
30+
> &nbsp;&nbsp; ( _NamedFunctionParam_ `,` )<sup>\*</sup> _NamedFunctionParam_ `,` `...`
31+
332
External blocks form the basis for Rust's foreign function interface.
433
Declarations in an external block describe symbols in external, non-Rust
534
libraries.
635

736
Functions within external blocks are declared in the same way as other Rust
837
functions, with the exception that they may not have a body and are instead
9-
terminated by a semicolon.
38+
terminated by a semicolon. Patterns are not allowed in parameters, only
39+
[IDENTIFIER] or `_` may be used.
1040

1141
Functions within external blocks may be called by Rust code, just like
1242
functions defined in Rust. The Rust compiler automatically translates between
@@ -23,8 +53,6 @@ extern {
2353

2454
A number of [attributes] control the behavior of external blocks.
2555

26-
[attributes]: attributes.html#ffi-attributes
27-
2856
By default external blocks assume that the library they are calling uses the
2957
standard C ABI on the specific platform. Other ABIs may be specified using an
3058
`abi` string, as shown here:
@@ -81,3 +109,16 @@ It is valid to add the `link` attribute on an empty extern block. You can use
81109
this to satisfy the linking requirements of extern blocks elsewhere in your
82110
code (including upstream crates) instead of adding the attribute to each extern
83111
block.
112+
113+
[IDENTIFIER]: identifiers.html
114+
[_Abi_]: items/functions.html
115+
[_FunctionParam_]: items/functions.html
116+
[_FunctionParameters_]: items/functions.html
117+
[_FunctionReturnType_]: items/functions.html
118+
[_Generics_]: items/generics.html
119+
[_InnerAttribute_]: attributes.html
120+
[_OuterAttribute_]: attributes.html
121+
[_Type_]: types.html
122+
[_Visibility_]: visibility-and-privacy.html
123+
[_WhereClause_]: items/generics.html#where-clauses
124+
[attributes]: attributes.html#ffi-attributes

‎src/items/functions.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,27 @@
11
# Functions
22

3+
> **<sup>Syntax</sup>**\
4+
> _Function_ :\
5+
> &nbsp;&nbsp; _FunctionFront_ `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
6+
> &nbsp;&nbsp; &nbsp;&nbsp; `(` _FunctionParameters_<sup>?</sup> `)`\
7+
> &nbsp;&nbsp; &nbsp;&nbsp; _FunctionReturnType_<sup>?</sup> [_WhereClause_]<sup>?</sup>\
8+
> &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
9+
>
10+
> _FunctionFront_ :\
11+
> &nbsp;&nbsp; `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
12+
>
13+
> _Abi_ :\
14+
> &nbsp;&nbsp; [STRING_LITERAL] | [RAW_STRING_LITERAL]
15+
>
16+
> _FunctionParameters_ :\
17+
> &nbsp;&nbsp; _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
18+
>
19+
> _FunctionParam_ :\
20+
> &nbsp;&nbsp; [_Pattern_] `:` [_Type_]
21+
>
22+
> _FunctionReturnType_ :\
23+
> &nbsp;&nbsp; `->` [_Type_]
24+
325
A _function_ consists of a [block], along with a name and a set of parameters.
426
Other than a name, all these are optional. Functions are declared with the
527
keyword `fn`. Functions may declare a set of *input* [*variables*][variables]
@@ -138,6 +160,16 @@ attributes], [`must_use`], [the procedural macro attributes], [the testing
138160
attributes], and [the optimization hint
139161
attributes].
140162

163+
[IDENTIFIER]: identifiers.html
164+
[RAW_STRING_LITERAL]: tokens.html#raw-string-literals
165+
[STRING_LITERAL]: tokens.html#string-literals
166+
[_BlockExpression_]: expressions/block-expr.html
167+
[_Generics_]: items/generics.html
168+
[_InnerAttribute_]: attributes.html
169+
[_Pattern_]: patterns.html
170+
[_Statement_]: statements.html
171+
[_Type_]: types.html
172+
[_WhereClause_]: items/generics.html#where-clauses
141173
[external blocks]: items/external-blocks.html
142174
[path]: paths.html
143175
[block]: expressions/block-expr.html

‎src/items/implementations.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,34 @@
11
# Implementations
22

3+
> **<sup>Syntax</sup>**\
4+
> _Implementation_ :\
5+
> &nbsp;&nbsp; _InherentImpl_ | _TraitImpl_
6+
>
7+
> _InherentImpl_ :\
8+
> &nbsp;&nbsp; `impl` [_Generics_]&nbsp;[_Type_]&nbsp;[_WhereClause_]<sup>?</sup> `{`\
9+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
10+
> &nbsp;&nbsp; &nbsp;&nbsp; _InherentImplItem_<sup>\*</sup>\
11+
> &nbsp;&nbsp; `}`
12+
>
13+
> _InherentImplItem_ :\
14+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
15+
> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
16+
> &nbsp;&nbsp; ( [_ConstantItem_] | [_Function_] | [_Method_] )
17+
>
18+
> _TraitImpl_ :\
19+
> &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_Generics_] `!`<sup>?</sup>
20+
> [_TypePath_] `for` [_Type_]\
21+
> &nbsp;&nbsp; [_WhereClause_]<sup>?</sup>\
22+
> &nbsp;&nbsp; `{`\
23+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
24+
> &nbsp;&nbsp; &nbsp;&nbsp; _TraitImplItem_<sup>\*</sup>\
25+
> &nbsp;&nbsp; `}`
26+
>
27+
> _TraitImplItem_ :\
28+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
29+
> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
30+
> &nbsp;&nbsp; ( [_TypeAlias_] | [_ConstantItem_] | [_Function_] | [_Method_] )
31+
332
An _implementation_ is an item that associates items with an _implementing type_.
433
Implementations are defined with the keyword `impl` and contain functions
534
that belong to an instance of the type that is being implemented or to the
@@ -59,6 +88,9 @@ The path to the associated items is `<` followed by a path to the implementing
5988
type followed by `as` followed by a path to the trait followed by `>` as a path
6089
component followed by the associated item's path component.
6190

91+
[Unsafe traits] require the trait implementation to begin with the `unsafe`
92+
keyword.
93+
6294
```rust
6395
# #[derive(Copy, Clone)]
6496
# struct Point {x: f64, y: f64};
@@ -143,9 +175,22 @@ attributes must come before any associated items. That attributes that have
143175
meaning here are [`cfg`], [`deprecated`], [`doc`], and [the lint check
144176
attributes].
145177

178+
[IDENTIFIER]: identifiers.html
179+
[_ConstantItem_]: items/constant-items.html
180+
[_Function_]: items/functions.html
181+
[_Generics_]: items/generics.html
182+
[_InnerAttribute_]: attributes.html
183+
[_Method_]: items/associated-items.html#methods
184+
[_OuterAttribute_]: attributes.html
185+
[_TypeAlias_]: items/type-aliases.html
186+
[_TypePath_]: paths.html#paths-in-types
187+
[_Type_]: types.html
188+
[_Visibility_]: visibility-and-privacy.html
189+
[_WhereClause_]: items/generics.html#where-clauses
146190
[trait]: items/traits.html
147191
[attributes]: attributes.html
148192
[`cfg`]: conditional-compilation.html
149193
[`deprecated`]: attributes.html#deprecation
150194
[`doc`]: attributes.html#documentation
151195
[the lint check attributes]: attributes.html#lint-check-attributes
196+
[Unsafe traits]: items/traits.html#unsafe-traits

‎src/items/traits.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,44 @@
11
# Traits
22

3+
> **<sup>Syntax</sup>**\
4+
> _Trait_ :\
5+
> &nbsp;&nbsp; `unsafe`<sup>?</sup> `trait` [IDENTIFIER]&nbsp;
6+
> [_Generics_]<sup>?</sup>
7+
> [_WhereClause_]<sup>?</sup> `{`\
8+
> &nbsp;&nbsp;&nbsp;&nbsp; _TraitItem_<sup>\*</sup>\
9+
> &nbsp;&nbsp; `}`
10+
>
11+
> _TraitItem_ :\
12+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (_TraitFunc_ | _TraitMethod_ | _TraitConst_ | _TraitType_)
13+
>
14+
> _TraitFunc_ :\
15+
> &nbsp;&nbsp; &nbsp;&nbsp; _TraitFunctionDecl_ ( `;` | [_BlockExpression_] )
16+
>
17+
> _TraitMethod_ :\
18+
> &nbsp;&nbsp; &nbsp;&nbsp; _TraitMethodDecl_ ( `;` | [_BlockExpression_] )
19+
>
20+
> _TraitFunctionDecl_ :\
21+
> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
22+
> &nbsp;&nbsp; &nbsp;&nbsp; `(` _TraitFunctionParameters_<sup>?</sup> `)`\
23+
> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
24+
>
25+
> _TraitMethodDecl_ :\
26+
> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
27+
> &nbsp;&nbsp; &nbsp;&nbsp; `(` [_SelfParam_] (`,` _TraitFunctionParam_)<sup>\*</sup> `,`<sup>?</sup> `)`\
28+
> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
29+
>
30+
> _TraitFunctionParameters_ :\
31+
> &nbsp;&nbsp; _TraitFunctionParam_ (`,` _TraitFunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
32+
>
33+
> _TraitFunctionParam_<sup>[†](#parameter-patterns)</sup> :\
34+
> &nbsp;&nbsp; ( [_Pattern_] `:` )<sup>?</sup> [_Type_]
35+
>
36+
> _TraitConst_ :\
37+
> &nbsp;&nbsp; `const` [IDENTIFIER] ( ( `:` [_Type_] ) ( `=` [_Expression_] )<sup>?</sup> )<sup>?</sup> `;`
38+
>
39+
> _TraitType_ :\
40+
> &nbsp;&nbsp; `type` [IDENTIFIER] ( `:` [_TypeParamBounds_] )<sup>?</sup> `;`
41+
342
A _trait_ describes an abstract interface that types can implement. This
443
interface consists of [associated items], which come in three varieties:
544

@@ -115,6 +154,63 @@ let circle = Box::new(circle) as Box<dyn Circle>;
115154
let nonsense = circle.radius() * circle.area();
116155
```
117156

157+
## Unsafe traits
158+
159+
Traits items that begin with the `unsafe` keyword indicate that *implementing* the
160+
trait may be [unsafe]. It is safe to use a correctly implemented unsafe trait.
161+
The [trait implementation] must also begin with the `unsafe` keyword.
162+
163+
[`Sync`] and [`Send`] are examples of unsafe traits.
164+
165+
## Parameter patterns
166+
167+
Function or method declarations without a body only allow [IDENTIFIER] or
168+
`_` [wild card][WildcardPattern] patterns. `mut` [IDENTIFIER] is currently
169+
allowed, but it is deprecated and will become a hard error in the future.
170+
<!-- https://github.com/rust-lang/rust/issues/35203 -->
171+
172+
In the 2015 edition, the pattern for a trait function or method parameter is
173+
optional:
174+
175+
```rust
176+
trait T {
177+
fn f(i32); // Parameter identifiers are not required.
178+
}
179+
```
180+
181+
The kinds of patterns for parameters is limited to one of the following:
182+
183+
* [IDENTIFIER]
184+
* `mut` [IDENTIFIER]
185+
* [`_`][WildcardPattern]
186+
* `&` [IDENTIFIER]
187+
* `&&` [IDENTIFIER]
188+
189+
Beginning in the 2018 edition, function or method parameter patterns are no
190+
longer optional. Also, all irrefutable patterns are allowed as long as there
191+
is a body. Without a body, the limitations listed above are still in effect.
192+
193+
```rust,edition2018
194+
trait T {
195+
fn f1((a, b): (i32, i32)) {}
196+
fn f2(_: (i32, i32)); // Cannot use tuple pattern without a body.
197+
}
198+
```
199+
200+
[IDENTIFIER]: identifiers.html
201+
[WildcardPattern]: patterns.html#wildcard-pattern
202+
[_BlockExpression_]: expressions/block-expr.html
203+
[_Expression_]: expressions.html
204+
[_FunctionFront_]: items/functions.html
205+
[_FunctionParam_]: items/functions.html
206+
[_FunctionReturnType_]: items/functions.html
207+
[_Generics_]: items/generics.html
208+
[_OuterAttribute_]: attributes.html
209+
[_Pattern_]: patterns.html
210+
[_SelfParam_]: items/associated-items.html#methods
211+
[_TypeParamBounds_]: trait-bounds.html
212+
[_Type_]: types.html
213+
[_WhereClause_]: items/generics.html#where-clauses
118214
[bounds]: trait-bounds.html
119215
[trait object]: types.html#trait-objects
120216
[explicit]: expressions/operator-expr.html#type-cast-expressions
@@ -125,3 +221,7 @@ let nonsense = circle.radius() * circle.area();
125221
[generics]: items/generics.html
126222
[where clauses]: items/generics.html#where-clauses
127223
[generic functions]: items/functions.html#generic-functions
224+
[unsafe]: unsafety.html
225+
[trait implementation]: items/implementations.html#trait-implementations
226+
[`Send`]: special-types-and-traits.html#send
227+
[`Sync`]: special-types-and-traits.html#sync

‎src/unsafety.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,15 @@ guarantees of Rust's static semantics.
66
The following language level features cannot be used in the safe subset of
77
Rust:
88

9-
- Dereferencing a [raw pointer](types.html#pointer-types).
10-
- Reading or writing a [mutable static variable](items/static-items.html#mutable-statics).
11-
- Reading a field of a [`union`](items/unions.html), or writing to a field of a
12-
union that isn't [`Copy`](special-types-and-traits.html#copy).
9+
- Dereferencing a [raw pointer].
10+
- Reading or writing a [mutable static variable].
11+
- Reading a field of a [`union`], or writing to a field of a
12+
union that isn't [`Copy`].
1313
- Calling an unsafe function (including an intrinsic or foreign function).
14-
- Implementing an unsafe trait.
14+
- Implementing an [unsafe trait].
15+
16+
[`Copy`]: special-types-and-traits.html#copy
17+
[`union`]: items/unions.html
18+
[mutable static variable]: items/static-items.html#mutable-statics
19+
[raw pointer]: types.html#pointer-types
20+
[unsafe trait]: items/traits.html#unsafe-traits

0 commit comments

Comments
 (0)