From 1bd23403eb7d5f40bb9d3e1fe39bf80dd476746a Mon Sep 17 00:00:00 2001 From: Bastian Kauschke Date: Wed, 11 Nov 2020 22:26:35 +0100 Subject: [PATCH 01/11] mention const generics --- src/const_eval.md | 2 ++ src/items/generics.md | 36 +++++++++++++++++++++++++++--------- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/src/const_eval.md b/src/const_eval.md index b3d087f32..5156e0268 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -20,6 +20,7 @@ also constant expressions and do not cause any [`Drop::drop`][destructors] calls to be run. * [Literals]. +* [Const parameters]. * [Paths] to [functions] and [constants]. Recursively defining constants is not allowed. * Paths to [statics]. These are only allowed within the initializer of a static. @@ -112,6 +113,7 @@ Conversely, the following are possible in a const function, but not in a const c [comparison]: expressions/operator-expr.md#comparison-operators [const functions]: items/functions.md#const-functions [constants]: items/constant-items.md +[Const parameters]: items/generics.md [dereference operator]: expressions/operator-expr.md#the-dereference-operator [destructors]: destructors.md [enum discriminants]: items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations diff --git a/src/items/generics.md b/src/items/generics.md index ba35e64d2..705f3707c 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -1,4 +1,4 @@ -# Type and Lifetime Parameters +# Generic parameters > **Syntax**\ > _Generics_ :\ @@ -6,7 +6,8 @@ > > _GenericParams_ :\ >       _LifetimeParams_\ ->    | ( _LifetimeParam_ `,` )\* _TypeParams_ +>    | ( _LifetimeParam_ `,` )\* _TypeParams_\ +>    | ( _LifetimeParam_ `,` )\* ( _TypeParam_ `,` )\* _ConstParams_ > > _LifetimeParams_ :\ >    ( _LifetimeParam_ `,` )\* _LifetimeParam_? @@ -18,20 +19,34 @@ >    ( _TypeParam_ `,` )\* _TypeParam_? > > _TypeParam_ :\ ->    [_OuterAttribute_]? [IDENTIFIER] ( `:` [_TypeParamBounds_]? )? ( `=` [_Type_] )? +>    [_OuterAttribute_]? [IDENTIFIER]( `:` [_TypeParamBounds_]? )? ( `=` [_Type_] )? +> +> _ConstParams_:\ +>    ( _ConstParam_ `,` )\* _ConstParam_? +> +> _ConstParam_:\ +>    [_OuterAttribute_]? `const` [IDENTIFIER] `:` [_Type_] Functions, type aliases, structs, enumerations, unions, traits, and -implementations may be *parameterized* by types and lifetimes. These parameters -are listed in angle brackets (`<...>`), +implementations may be *parameterized* by types, constants and lifetimes. These +parameters are listed in angle brackets (`<...>`), usually immediately after the name of the item and before its definition. For implementations, which don't have a name, they come directly after `impl`. -Lifetime parameters must be declared before type parameters. Some examples of -items with type and lifetime parameters: +The order of generic parameters is restricted to lifetime parameters, then type parameters and then const parameters. + +The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize` +`i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`. +Const parameters may only be be used as standalone arguments inside +of [types] and [repeat expressions]. +They can be used freely outside of [const contexts]. + +Some examples of items with type, const and lifetime parameters: ```rust fn foo<'a, T>() {} trait A {} struct Ref<'a, T> where T: 'a { r: &'a T } +struct InnerArray([T; N]); ``` [References], [raw pointers], [arrays], [slices][arrays], [tuples], and @@ -65,7 +80,7 @@ Bounds that don't use the item's parameters or higher-ranked lifetimes are checked when the item is defined. It is an error for such a bound to be false. [`Copy`], [`Clone`], and [`Sized`] bounds are also checked for certain generic -types when defining the item. It is an error to have `Copy` or `Clone`as a +types when defining the item. It is an error to have `Copy` or `Clone` as a bound on a mutable reference, [trait object] or [slice][arrays] or `Sized` as a bound on a trait object or slice. @@ -112,12 +127,15 @@ struct Foo<#[my_flexible_clone(unbounded)] H> { [_TypeParamBounds_]: ../trait-bounds.md [arrays]: ../types/array.md +[const contexts]: ../const_eval.md#const-context [function pointers]: ../types/function-pointer.md -[references]: ../types/pointer.md#shared-references- [raw pointers]: ../types/pointer.md#raw-pointers-const-and-mut +[references]: ../types/pointer.md#shared-references +[repeat expressions]: ../expressions/array-expr.md [`Clone`]: ../special-types-and-traits.md#clone [`Copy`]: ../special-types-and-traits.md#copy [`Sized`]: ../special-types-and-traits.md#sized [tuples]: ../types/tuple.md [trait object]: ../types/trait-object.md +[types]: ../types.md [attributes]: ../attributes.md From 1c55d2790c738ddffc696ad065163a9766ca9e2f Mon Sep 17 00:00:00 2001 From: lcnr Date: Sun, 27 Dec 2020 16:04:37 +0100 Subject: [PATCH 02/11] Update src/const_eval.md Co-authored-by: est31 --- src/const_eval.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/const_eval.md b/src/const_eval.md index 5156e0268..159f0a768 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -113,7 +113,7 @@ Conversely, the following are possible in a const function, but not in a const c [comparison]: expressions/operator-expr.md#comparison-operators [const functions]: items/functions.md#const-functions [constants]: items/constant-items.md -[Const parameters]: items/generics.md +[Const parameters]: items/generics.md [dereference operator]: expressions/operator-expr.md#the-dereference-operator [destructors]: destructors.md [enum discriminants]: items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations From fec814c47d7c01ac423f5e9fced2af83a3b34b67 Mon Sep 17 00:00:00 2001 From: lcnr Date: Tue, 29 Dec 2020 20:01:46 +0100 Subject: [PATCH 03/11] Update src/items/generics.md Co-authored-by: Eric Huss --- src/items/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/generics.md b/src/items/generics.md index 705f3707c..6f52d5858 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -32,7 +32,7 @@ implementations may be *parameterized* by types, constants and lifetimes. These parameters are listed in angle brackets (`<...>`), usually immediately after the name of the item and before its definition. For implementations, which don't have a name, they come directly after `impl`. -The order of generic parameters is restricted to lifetime parameters, then type parameters and then const parameters. +The order of generic parameters is restricted to lifetime parameters, then type parameters, and then const parameters. The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize` `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`. From ce44ec24758d5563e0e4108bfc1c906f2eb31beb Mon Sep 17 00:00:00 2001 From: lcnr Date: Tue, 29 Dec 2020 20:01:53 +0100 Subject: [PATCH 04/11] Update src/items/generics.md Co-authored-by: Eric Huss --- src/items/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/generics.md b/src/items/generics.md index 6f52d5858..c413b274f 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -28,7 +28,7 @@ >    [_OuterAttribute_]? `const` [IDENTIFIER] `:` [_Type_] Functions, type aliases, structs, enumerations, unions, traits, and -implementations may be *parameterized* by types, constants and lifetimes. These +implementations may be *parameterized* by types, constants, and lifetimes. These parameters are listed in angle brackets (`<...>`), usually immediately after the name of the item and before its definition. For implementations, which don't have a name, they come directly after `impl`. From 7c659ad560a7ce2179bf685bc2d3b66f368ea517 Mon Sep 17 00:00:00 2001 From: lcnr Date: Tue, 29 Dec 2020 20:01:58 +0100 Subject: [PATCH 05/11] Update src/items/generics.md Co-authored-by: Eric Huss --- src/items/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/generics.md b/src/items/generics.md index c413b274f..4a5a3abf8 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -40,7 +40,7 @@ Const parameters may only be be used as standalone arguments inside of [types] and [repeat expressions]. They can be used freely outside of [const contexts]. -Some examples of items with type, const and lifetime parameters: +Some examples of items with type, const, and lifetime parameters: ```rust fn foo<'a, T>() {} From 49f9b34687a3e45c5839f5bbcf9c5ad49c88081f Mon Sep 17 00:00:00 2001 From: Bastian Kauschke Date: Tue, 29 Dec 2020 20:07:09 +0100 Subject: [PATCH 06/11] review --- src/SUMMARY.md | 2 +- src/items/generics.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index fb0e6574d..bd9cb9ca7 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -35,7 +35,7 @@ - [Traits](items/traits.md) - [Implementations](items/implementations.md) - [External blocks](items/external-blocks.md) - - [Type and lifetime parameters](items/generics.md) + - [Generic parameters](items/generics.md) - [Associated Items](items/associated-items.md) - [Visibility and Privacy](visibility-and-privacy.md) diff --git a/src/items/generics.md b/src/items/generics.md index 4a5a3abf8..900b11e9d 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -70,7 +70,7 @@ referred to with path syntax. >    _ForLifetimes_? [_Type_] `:` [_TypeParamBounds_]? > > _ForLifetimes_ :\ ->    `for` `<` [_LifetimeParams_](#type-and-lifetime-parameters) `>` +>    `for` `<` [_LifetimeParams_](#generic-parameters) `>` *Where clauses* provide another way to specify bounds on type and lifetime parameters as well as a way to specify bounds on types that aren't type @@ -130,7 +130,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> { [const contexts]: ../const_eval.md#const-context [function pointers]: ../types/function-pointer.md [raw pointers]: ../types/pointer.md#raw-pointers-const-and-mut -[references]: ../types/pointer.md#shared-references +[references]: ../types/pointer.md#shared-references- [repeat expressions]: ../expressions/array-expr.md [`Clone`]: ../special-types-and-traits.md#clone [`Copy`]: ../special-types-and-traits.md#copy From 210191a9951ed5ac4d181218010eafbd6b857017 Mon Sep 17 00:00:00 2001 From: Bastian Kauschke Date: Tue, 29 Dec 2020 20:31:42 +0100 Subject: [PATCH 07/11] generics --- src/items/generics.md | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/src/items/generics.md b/src/items/generics.md index 900b11e9d..c5c9053f8 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -34,12 +34,6 @@ usually immediately after the name of the item and before its definition. For implementations, which don't have a name, they come directly after `impl`. The order of generic parameters is restricted to lifetime parameters, then type parameters, and then const parameters. -The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize` -`i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`. -Const parameters may only be be used as standalone arguments inside -of [types] and [repeat expressions]. -They can be used freely outside of [const contexts]. - Some examples of items with type, const, and lifetime parameters: ```rust @@ -49,6 +43,33 @@ struct Ref<'a, T> where T: 'a { r: &'a T } struct InnerArray([T; N]); ``` +The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize` +`i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`. + +Const parameters may only be be used as standalone arguments inside +of [types] and [repeat expressions] but may be freely used elsewhere: + +```rust +// ok: standalone argument +fn foo() -> [u8; N] { todo!() } + +// ERROR: generic const operation +fn bar() -> [u8; N + 1] { todo!() } +``` + +Unlike type and lifetime parameters, const parameters of types can be used without +being mentioned inside of a parameterized type: + +```rust +// ok +struct Foo; +enum Bar { A, B } + +// ERROR: unused parameter +struct Baz; +struct Biz<'a>; +``` + [References], [raw pointers], [arrays], [slices][arrays], [tuples], and [function pointers] have lifetime or type parameters as well, but are not referred to with path syntax. From bd714f66265cbf4594b5e19c9aad205026632750 Mon Sep 17 00:00:00 2001 From: Bastian Kauschke Date: Tue, 29 Dec 2020 20:49:32 +0100 Subject: [PATCH 08/11] update generic arg docs --- src/paths.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/src/paths.md b/src/paths.md index 821d883d1..9126e5bbe 100644 --- a/src/paths.md +++ b/src/paths.md @@ -52,11 +52,16 @@ mod m { >       `<` `>`\ >    | `<` _GenericArgsLifetimes_ `,`? `>`\ >    | `<` _GenericArgsTypes_ `,`? `>`\ +>    | `<` _GenericArgsConsts_ `,`? `>`\ >    | `<` _GenericArgsBindings_ `,`? `>`\ ->    | `<` _GenericArgsTypes_ `,` _GenericArgsBindings_ `,`? `>`\ >    | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,`? `>`\ +>    | `<` _GenericArgsLifetimes_ `,` _GenericArgsConsts_ `,`? `>`\ >    | `<` _GenericArgsLifetimes_ `,` _GenericArgsBindings_ `,`? `>`\ ->    | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsBindings_ `,`? `>` +>    | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsConsts_ `,`? `>`\ +>    | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsBindings_ `,`? `>`\ +>    | `<` _GenericArgsLifetimes_ `,` _GenericArgsConsts_ `,` _GenericArgsBindings_ `,`? `>`\ +>    | `<` _GenericArgsTypes_ `,` _GenericArgsConsts_ `,` _GenericArgsBindings_ `,`? `>`\ +>    | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsConsts_ `,` _GenericArgsBindings_ `,`? `>` > > _GenericArgsLifetimes_ :\ >    [_Lifetime_] (`,` [_Lifetime_])\* @@ -64,6 +69,9 @@ mod m { > _GenericArgsTypes_ :\ >    [_Type_] (`,` [_Type_])\* > +> _GenericArgsConsts_ :\ +>    [_Expression_] (`,` [_Expression_])\* +> > _GenericArgsBindings_ :\ >    _GenericArgsBinding_ (`,` _GenericArgsBinding_)\* > @@ -81,6 +89,9 @@ ambiguity with the less-than operator. This is colloquially known as "turbofish" Vec::::with_capacity(1024); ``` +Const arguments must be surrounded by braces unless they are a +[literal] or a single segment path. + ## Qualified paths > **Syntax**\ @@ -367,6 +378,8 @@ mod without { // ::without [_GenericArgs_]: #paths-in-expressions [_Lifetime_]: trait-bounds.md [_Type_]: types.md#type-expressions +[_Expression_]: expressions.md +[literal]: expressions/literal-expr.md [item]: items.md [variable]: variables.md [implementations]: items/implementations.md From 9fe55ae71280bb89a61378bc1d1dd0b1e56c12d1 Mon Sep 17 00:00:00 2001 From: Bastian Kauschke Date: Tue, 29 Dec 2020 20:55:35 +0100 Subject: [PATCH 09/11] asd --- src/items/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/generics.md b/src/items/generics.md index c5c9053f8..f3d6027e4 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -49,7 +49,7 @@ The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128` Const parameters may only be be used as standalone arguments inside of [types] and [repeat expressions] but may be freely used elsewhere: -```rust +```rust,should_panic // ok: standalone argument fn foo() -> [u8; N] { todo!() } From 4ec984b848fcbd9262c9498a0a9965413f4a7913 Mon Sep 17 00:00:00 2001 From: Bastian Kauschke Date: Tue, 29 Dec 2020 21:03:37 +0100 Subject: [PATCH 10/11] asd --- src/items/generics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/items/generics.md b/src/items/generics.md index f3d6027e4..abb50b47f 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -49,7 +49,7 @@ The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128` Const parameters may only be be used as standalone arguments inside of [types] and [repeat expressions] but may be freely used elsewhere: -```rust,should_panic +```rust,compile_fail // ok: standalone argument fn foo() -> [u8; N] { todo!() } @@ -60,7 +60,7 @@ fn bar() -> [u8; N + 1] { todo!() } Unlike type and lifetime parameters, const parameters of types can be used without being mentioned inside of a parameterized type: -```rust +```rust,compile_fail // ok struct Foo; enum Bar { A, B } From 15ec5a6f6c9c867242cb231413094dd4568babb2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 1 Jan 2021 11:27:57 -0800 Subject: [PATCH 11/11] Update _GenericArgsConsts_ grammar. --- src/paths.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/paths.md b/src/paths.md index 9126e5bbe..47a14ee91 100644 --- a/src/paths.md +++ b/src/paths.md @@ -70,7 +70,13 @@ mod m { >    [_Type_] (`,` [_Type_])\* > > _GenericArgsConsts_ :\ ->    [_Expression_] (`,` [_Expression_])\* +>    _GenericArgsConst_ (`,` _GenericArgsConst_)\* +> +> _GenericArgsConst_ :\ +>       [_BlockExpression_]\ +>    | [_LiteralExpression_]\ +>    | `-` [_LiteralExpression_]\ +>    | [_SimplePathSegment_] > > _GenericArgsBindings_ :\ >    _GenericArgsBinding_ (`,` _GenericArgsBinding_)\* @@ -375,10 +381,13 @@ mod without { // ::without # fn main() {} ``` +[_BlockExpression_]: expressions/block-expr.md +[_Expression_]: expressions.md [_GenericArgs_]: #paths-in-expressions [_Lifetime_]: trait-bounds.md +[_LiteralExpression_]: expressions/literal-expr.md +[_SimplePathSegment_]: #simple-paths [_Type_]: types.md#type-expressions -[_Expression_]: expressions.md [literal]: expressions/literal-expr.md [item]: items.md [variable]: variables.md