From 9c5e61647d68e0244dd1eb41db544e9a7944e714 Mon Sep 17 00:00:00 2001 From: Havvy Date: Sun, 8 Oct 2017 07:55:44 -0700 Subject: [PATCH 1/5] Implementations improvements part 1 Trying to not focus on what it means to associate a type, nor deal too much with generic impls at this point. --- src/glossary.md | 21 ++++++- src/items/implementations.md | 111 ++++++++++++++++++++++++++++------- 2 files changed, 109 insertions(+), 23 deletions(-) diff --git a/src/glossary.md b/src/glossary.md index 44f308e88..b7a4334ef 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -8,7 +8,7 @@ the structure of the program when the compiler is compiling it. ### Arity Arity refers to the number of arguments a function or operation takes. -For example, `(2, 3)` and `(4, 6)` have arity 2, and`(8, 2, 6)` has arity 3. +For example, `f(2, 3)` and `g(4, 6)` have arity 2, while `h(8, 2, 6)` has arity 3. ### Array @@ -16,6 +16,13 @@ An array, sometimes also called a fixed-size array or an inline array, is a valu describing a collection of elements, each selected by an index that can be computed at run time by the program. It occupies a contiguous region of memory. +### Associated Item + +An associated item is an item that is associated with another item. Associated +items are defined in [implementations] and [traits]. Only functions, constants, +and types can be associated. + + ### Bound Bounds are constraints on a type or trait. For example, if a bound @@ -52,6 +59,11 @@ A variable is initialized if it has been assigned a value and hasn't since been moved from. All other lvalues are assumed to be initialized. Only unsafe Rust can create such an lvalue without initializing it. +### Nominal Types + +Types that can be named directly. Specifically [enums], [structs], [unions], +and [trait objects]. + ### Prelude Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are @@ -91,3 +103,10 @@ A trait is a language item that is used for describing the functionalities a typ It allow a type to make certain promises about its behavior. Generic functions and generic structs can exploit traits to constrain, or bound, the types they accept. + +[enums]: items/enumerations.html +[structs]: items/structs.html +[unions]: items/unions.html +[trait objects]: types.html#trait-objects +[implementations]: items/implementations.html +[traits]: items/traits.html \ No newline at end of file diff --git a/src/items/implementations.md b/src/items/implementations.md index 51330570c..d377057d7 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -1,10 +1,64 @@ # Implementations -An _implementation_ is an item that can implement a [trait](items/traits.html) for a -specific type. +An _implementation_ is an item that associates items with a *implementing type*. + +There are two types of implementations: Bare implementations and [trait] +implementations. Implementations are defined with the keyword `impl`. +## Bare Implementations + +A bare implementation is defined as the keyword `impl` optionally followed by +generic type declarations followed by a [nominal] type optionally followed by +where clauses followed by a container of braces of a set of zero or more +associable items. + +The nominal type is called the *implementing type* and the associable items are +the *associated items* to the implementing type. + +Bare implementations associates the associated items to the implementing type. + +The associated item has a canonical path of the canonical path of the +implementing type followed by the associate item's path component. + +A type can have multiple bare implementations. + +The implementing type must be defined within the same crate. + +```rust +struct Point {x: i32, y: i32} + +impl Point { + fn log(&self) { + println!("Point is at ({}, {})", self.x, self.y); + } +} + +let my_point = Point {x: 10, y:11}; +my_point.log(); +``` + +## Trait Implementations + +A *trait implementation* is defined like a bare implementation except that +the optional generic type declarations is followed by a trait followed +by the keyword `for`. + +The trait is known as the *implemented trait*. + +The implementing type implements the implemented trait. + +A trait implementation must define all non-default associated items declared +by the implemented trait, may redefine default associated items defined by the +implemented trait trait, and cannot define any other items. + +The canonical path to the associated items is `<` followed by the canonical path +of the implementing type followed by `as` followed by the canonical path to the +trait followed by `>` as a path component followed by the associated item's path +component. + ```rust # #[derive(Copy, Clone)] # struct Point {x: f64, y: f64}; @@ -37,33 +91,43 @@ impl Shape for Circle { } ``` -It is possible to define an implementation without referring to a trait. The -methods in such an implementation can only be used as direct calls on the -values of the type that the implementation targets. In such an implementation, -the trait type and `for` after `impl` are omitted. Such implementations are -limited to nominal types (enums, structs, unions, trait objects), and the -implementation must appear in the same crate as the `Self` type: +### Trait Implementation Coherence -```rust -struct Point {x: i32, y: i32} +A trait implementation is consider incoherent if either the orphan check fails +or there are overlapping implementation instaces. -impl Point { - fn log(&self) { - println!("Point is at ({}, {})", self.x, self.y); - } -} +Two trait implementations overlap when there is a non-empty intersection of the +traits the implementation is for, the implementations can be instantiated with +the same type. -let my_point = Point {x: 10, y:11}; -my_point.log(); -``` +The `Orphan Check` states that every trait implementation must meet either of +the following conditions: -When a trait _is_ specified in an `impl`, all methods declared as part of the -trait must be implemented, with matching types and type parameter counts. +1. The trait being implemented is defined in the same crate. + +2. At least one of either `Self` or a generic type parameter of the trait must + meet the following grammar, where `C` is a nominal type defined + within the containing crate: + + ``` + T = C + | [T] + | [T, ..n] + | &T + | &mut T + | Box + | (..., T, ...) + | X<..., T, ...> where X is not bivariant with respect to T + ``` + +## Generic Implementations An implementation can take type and lifetime parameters, which can be used in the rest of the implementation. Type parameters declared for an implementation -must be used at least once in either the trait or the type of an -implementation. Implementation parameters are written after the `impl` keyword. +must be used at least once in either the trait or the implementing type of an +implementation. Implementation parameters are written directly after the `impl` +keyword. ```rust # trait Seq { fn dummy(&self, _: T) { } } @@ -74,3 +138,6 @@ impl Seq for u32 { /* Treat the integer as a sequence of bits */ } ``` + + +[trait]: items/traits.html \ No newline at end of file From 00b68334f370bbbcb2e320031a8583e5c3b19638 Mon Sep 17 00:00:00 2001 From: Havvy Date: Fri, 27 Oct 2017 00:55:22 -0700 Subject: [PATCH 2/5] Changes suggested by Rantanen on IRC --- src/items/implementations.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index d377057d7..0ed3f8cb5 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -1,6 +1,6 @@ # Implementations -An _implementation_ is an item that associates items with a *implementing type*. +An _implementation_ is an item that associates items with an *implementing type*. There are two types of implementations: Bare implementations and [trait] implementations. @@ -11,16 +11,22 @@ Implementations are defined with the keyword `impl`. A bare implementation is defined as the keyword `impl` optionally followed by generic type declarations followed by a [nominal] type optionally followed by -where clauses followed by a container of braces of a set of zero or more -associable items. +where clauses followed by a set of zero or more associable items contained +within braces. + +sequence of 'impl' keyword, generic type declarations, nominal type, where clause and the associable items. Generic type declarations and where clause can be omitted, if not needed. The associable items are contained within braces. + +A bare implementation is defined as the sequence of the `impl` keyword, generic +type declarations, a path to a nomial tyupe, a where clause, and a bracketed +set of associable items. The nominal type is called the *implementing type* and the associable items are the *associated items* to the implementing type. Bare implementations associates the associated items to the implementing type. -The associated item has a canonical path of the canonical path of the -implementing type followed by the associate item's path component. +The associated item has a path of a path to the implementing type followed by +the associate item's path component. A type can have multiple bare implementations. @@ -54,10 +60,9 @@ A trait implementation must define all non-default associated items declared by the implemented trait, may redefine default associated items defined by the implemented trait trait, and cannot define any other items. -The canonical path to the associated items is `<` followed by the canonical path -of the implementing type followed by `as` followed by the canonical path to the -trait followed by `>` as a path component followed by the associated item's path -component. +The path to the associated items is `<` followed by a path to the implementing +type followed by `as` followed by a path to the trait followed by `>` as a path +component followed by the associated item's path component. ```rust # #[derive(Copy, Clone)] @@ -110,7 +115,7 @@ the following conditions: meet the following grammar, where `C` is a nominal type defined within the containing crate: - ``` + ```ignore T = C | [T] | [T, ..n] From 2aea016051c51bde09a67b035b3f509011ec0be8 Mon Sep 17 00:00:00 2001 From: Havvy Date: Sat, 28 Oct 2017 12:44:41 -0700 Subject: [PATCH 3/5] Address Matthew Jasper's points. --- src/items/implementations.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 0ed3f8cb5..bdf061afa 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -9,13 +9,6 @@ Implementations are defined with the keyword `impl`. ## Bare Implementations -A bare implementation is defined as the keyword `impl` optionally followed by -generic type declarations followed by a [nominal] type optionally followed by -where clauses followed by a set of zero or more associable items contained -within braces. - -sequence of 'impl' keyword, generic type declarations, nominal type, where clause and the associable items. Generic type declarations and where clause can be omitted, if not needed. The associable items are contained within braces. - A bare implementation is defined as the sequence of the `impl` keyword, generic type declarations, a path to a nomial tyupe, a where clause, and a bracketed set of associable items. @@ -23,7 +16,7 @@ set of associable items. The nominal type is called the *implementing type* and the associable items are the *associated items* to the implementing type. -Bare implementations associates the associated items to the implementing type. +Bare implementations associate the associated items to the implementing type. The associated item has a path of a path to the implementing type followed by the associate item's path component. @@ -117,13 +110,9 @@ the following conditions: ```ignore T = C - | [T] - | [T, ..n] | &T | &mut T | Box - | (..., T, ...) - | X<..., T, ...> where X is not bivariant with respect to T ``` ## Generic Implementations From f5d91fa0d595ab19ec38a3b4740ae6ed13e9280e Mon Sep 17 00:00:00 2001 From: Havvy Date: Fri, 3 Nov 2017 14:44:25 -0700 Subject: [PATCH 4/5] Address most of scottmcm's comments. --- src/glossary.md | 18 +++++++++--------- src/items/implementations.md | 4 +++- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/src/glossary.md b/src/glossary.md index b7a4334ef..16f3bc2ef 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -7,8 +7,9 @@ the structure of the program when the compiler is compiling it. ### Arity -Arity refers to the number of arguments a function or operation takes. -For example, `f(2, 3)` and `g(4, 6)` have arity 2, while `h(8, 2, 6)` has arity 3. +Arity refers to the number of arguments a function or operator takes. +For some examples, `f(2, 3)` and `g(4, 6)` have arity 2, while `h(8, 2, 6)` +has arity 3. The `!` operator has arity 1. ### Array @@ -19,9 +20,8 @@ at run time by the program. It occupies a contiguous region of memory. ### Associated Item An associated item is an item that is associated with another item. Associated -items are defined in [implementations] and [traits]. Only functions, constants, -and types can be associated. - +items are defined in [implementations] and declared in [traits]. Only functions, +constants, and type aliases can be associated. ### Bound @@ -61,8 +61,8 @@ can create such an lvalue without initializing it. ### Nominal Types -Types that can be named directly. Specifically [enums], [structs], [unions], -and [trait objects]. +Types that can be referred to by a path directly. Specifically [enums], +[structs], [unions], and [trait objects]. ### Prelude @@ -100,9 +100,9 @@ Strings slices are always valid UTF-8. ### Trait A trait is a language item that is used for describing the functionalities a type must provide. -It allow a type to make certain promises about its behavior. +It allows a type to make certain promises about its behavior. -Generic functions and generic structs can exploit traits to constrain, or bound, the types they accept. +Generic functions and generic structs can use traits to constrain, or bound, the types they accept. [enums]: items/enumerations.html [structs]: items/structs.html diff --git a/src/items/implementations.md b/src/items/implementations.md index bdf061afa..7f95eb635 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -10,7 +10,7 @@ Implementations are defined with the keyword `impl`. ## Bare Implementations A bare implementation is defined as the sequence of the `impl` keyword, generic -type declarations, a path to a nomial tyupe, a where clause, and a bracketed +type declarations, a path to a nomial type, a where clause, and a bracketed set of associable items. The nominal type is called the *implementing type* and the associable items are @@ -21,6 +21,8 @@ Bare implementations associate the associated items to the implementing type. The associated item has a path of a path to the implementing type followed by the associate item's path component. +Bare implementations cannot contain associated type aliases. + A type can have multiple bare implementations. The implementing type must be defined within the same crate. From a05175446560b32419fbe1c845d5b125702846ba Mon Sep 17 00:00:00 2001 From: Havvy Date: Wed, 22 Nov 2017 00:54:19 -0800 Subject: [PATCH 5/5] bare -> inherent --- src/items/implementations.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 7f95eb635..b76ac6d97 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -2,28 +2,29 @@ An _implementation_ is an item that associates items with an *implementing type*. -There are two types of implementations: Bare implementations and [trait] +There are two types of implementations: inherent implementations and [trait] implementations. Implementations are defined with the keyword `impl`. -## Bare Implementations +## Interent Implementations -A bare implementation is defined as the sequence of the `impl` keyword, generic -type declarations, a path to a nomial type, a where clause, and a bracketed -set of associable items. +An inherent implementation is defined as the sequence of the `impl` keyword, +generic type declarations, a path to a nomial type, a where clause, and a +bracketed set of associable items. The nominal type is called the *implementing type* and the associable items are the *associated items* to the implementing type. -Bare implementations associate the associated items to the implementing type. +Inherent implementations associate the associated items to the implementing +type. The associated item has a path of a path to the implementing type followed by the associate item's path component. -Bare implementations cannot contain associated type aliases. +Inherent implementations cannot contain associated type aliases. -A type can have multiple bare implementations. +A type can have multiple inherent implementations. The implementing type must be defined within the same crate. @@ -42,8 +43,8 @@ my_point.log(); ## Trait Implementations -A *trait implementation* is defined like a bare implementation except that -the optional generic type declarations is followed by a trait followed +A *trait implementation* is defined like an inherent implementation except that +the optional generic type declarations is followed by a [trait] followed by the keyword `for`.