From 025a9fdc673915fe8fdc4f9c0d80c0e874ffeb71 Mon Sep 17 00:00:00 2001 From: Alexis Hunt Date: Sun, 18 Mar 2018 13:24:43 -0400 Subject: [PATCH] More cleanups related to methods. Also re-add a description of provided implementations. --- src/expressions/method-call-expr.md | 9 +++++---- src/items/associated-items.md | 6 +++++- src/items/functions.md | 16 +++++++--------- src/items/traits.md | 22 +++++++++++++--------- 4 files changed, 30 insertions(+), 23 deletions(-) diff --git a/src/expressions/method-call-expr.md b/src/expressions/method-call-expr.md index 62859cffdfe73..e8defac23e78e 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -2,10 +2,10 @@ A _method call_ consists of an expression (the *receiver*) followed by a single dot, an [identifier], and a parenthesized expression-list. Method calls are -resolved to associated methods of specific types, either statically dispatching -to a method if the exact `self`-type of the left-hand-side is known, or -dynamically dispatching if the left-hand-side expression is an indirect [trait -object](types.html#trait-objects). +resolved to associated [methods] on specific traits, either statically +dispatching to a method if the exact `self`-type of the left-hand-side is known, +or dynamically dispatching if the left-hand-side expression is an indirect +[trait object](types.html#trait-objects). ```rust let pi: Result = "3.14".parse(); @@ -95,3 +95,4 @@ and function invocation. [trait objects]: types.html#trait-objects [disambiguate call]: expressions/call-expr.html#disambiguating-function-calls [dereference]: expressions/operator-expr.html#the-dereference-operator +[methods]: items/associated-items.html#methods diff --git a/src/items/associated-items.md b/src/items/associated-items.md index e52fd4024e05e..4b2db67abbeca 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -77,15 +77,19 @@ let _: f64 = ::from_i32(42); let _: f64 = f64::from_i32(42); ``` +### Methods + Associated functions whose first parameter is named `self` are called *methods* and may be invoked using the [method call operator], for example, `x.foo()`, as well as the usual function call notation. -When the first parameter is named `self`, the following shorthands may be used. +The `self` parameter must have one of the following types. As a result, the +following shorthands may be used to declare `self`: * `self` -> `self: Self` * `&'lifetime self` -> `self: &'lifetime Self` * `&'lifetime mut self` -> `self: &'lifetime mut Self` +* `self : Box` (no shorthand) > Note: Lifetimes can be and usually are elided with this shorthand. diff --git a/src/items/functions.md b/src/items/functions.md index 0ccdeaa61a5d1..deff960c85b4d 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -7,16 +7,10 @@ as parameters, through which the caller passes arguments into the function, and the *output* [*type*][type] of the value the function will return to its caller on completion. -[block]: expressions/block-expr.html -[variables]: variables.html -[type]: types.html - When referred to, a _function_ yields a first-class *value* of the corresponding zero-sized [*function item type*], which when called evaluates to a direct call to the function. -[*function item type*]: types.html#function-item-types - For example, this is a simple function: ```rust fn answer_to_life_the_universe_and_everything() -> i32 { @@ -61,7 +55,7 @@ fn foo(x: A, y: B) { ``` Inside the function signature and body, the name of the type parameter can be -used as a type name. [Trait](items/traits.html) bounds can be specified for type +used as a type name. [Trait] bounds can be specified for type parameters to allow methods with that trait to be called on values of that type. This is specified using the `where` syntax: @@ -91,8 +85,6 @@ component after the function name. This might be necessary if there is not sufficient context to determine the type parameters. For example, `mem::size_of::() == 4`. -[path]: paths.html - ## Extern functions Extern functions are part of Rust's foreign function interface, providing the @@ -124,3 +116,9 @@ of an extern function will cause the process to abort. In LLVM, this is implemented by executing an illegal instruction. [external blocks]: items/external-blocks.html +[path]: paths.html +[block]: expressions/block-expr.html +[variables]: variables.html +[type]: types.html +[*function item type*]: types.html#function-item-types +[Trait]: items/traits.html diff --git a/src/items/traits.md b/src/items/traits.md index cca70b09b5022..bffa7c61d118f 100644 --- a/src/items/traits.md +++ b/src/items/traits.md @@ -14,14 +14,19 @@ other traits and so forth as usual. Traits are implemented for specific types through separate [implementations]. +Items associated with a trait do not need to be defined in the trait, but they +may be. If the trait provides a definition, then this definition acts as a +default for any implementation which does not override it. If it does not, then +any implementation must provide a definition. + ## Trait bounds Generic functions may use traits as _bounds_ on their type parameters. This will have three effects: - Only types that have the trait may instantiate the parameter. -- Within the generic function, the methods of the trait can be called on values - that have the parameter's type. Associated types can be used in the +- Within the generic function, the functions of the trait can be called on + values that have the parameter's type. Associated types can be used in the function's signature, and associated constants can be used in expressions within the function body. - Generic functions and types with the same or weaker bounds can use the @@ -63,11 +68,10 @@ Object safe traits can be the base trait of a [trait object]. A trait is *object safe* if it has the following qualities (defined in [RFC 255]): * It must not require `Self: Sized` -* All associated functions must either have a `where Self: Sized` bound or - * Not have any type parameters (although lifetime parameters are allowed) - * Must be a method: its first parameter must be called self, with type - `Self`, `&Self`, `&mut Self`, `Box`. - * `Self` may only be used in the type of the receiver. +* All associated functions must either have a `where Self: Sized` bound, or + * Not have any type parameters (although lifetime parameters are allowed), + and + * Be a [method] that does not use `Self` except in the type of the receiver. * It must not have any associated constants. ## Supertraits @@ -142,6 +146,6 @@ let nonsense = mycircle.radius() * mycircle.area(); [`RefUnwindSafe`]: ../std/panic/trait.RefUnwindSafe.html [trait object]: types.html#trait-objects [explicit]: expressions/operator-expr.html#type-cast-expressions -[methods called]: expressions/method-call-expr.html [RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md -[associated items]: items/associated-items.html \ No newline at end of file +[associated items]: items/associated-items.html +[method]: items/functions.html#methods