|
3 | 3 | /// Cast between types, or rename an import. |
4 | 4 | /// |
5 | 5 | /// `as` is most commonly used to turn primitive types into other primitive types, but it has other |
6 | | -/// uses that include turning pointers into addresses, addresses into pointers, and pointers into |
7 | | -/// other pointers. |
| 6 | +/// uses that include turning pointers into addresses, addresses into pointers, pointers into |
| 7 | +/// other pointers, and qualifying paths for associated items. |
8 | 8 | /// |
9 | 9 | /// ```rust |
10 | 10 | /// let thing1: u8 = 89.0 as u8; |
|
37 | 37 | /// use std::{mem as memory, net as network}; |
38 | 38 | /// // Now you can use the names `memory` and `network` to refer to `std::mem` and `std::net`. |
39 | 39 | /// ``` |
40 | | -/// For more information on what `as` is capable of, see the [Reference]. |
41 | | -/// |
42 | | -/// [Reference]: ../reference/expressions/operator-expr.html#type-cast-expressions |
| 40 | +/// You'll also find with `From` and `Into`, and indeed all traits, that `as` is used for the |
| 41 | +/// _fully qualified path_, a means of disambiguating associated items, i.e. functions, |
| 42 | +/// constants, and types. For example, if you have a type which implements two traits with identical |
| 43 | +/// method names (e.g. `Into::<u32>::into` and `Into::<u64>::into`), you can clarify which method |
| 44 | +/// you'll use with `<MyThing as Into<u32>>::into(my_thing)`[^as-use-from]. This is quite verbose, |
| 45 | +/// but fortunately, Rust's type inference usually saves you from needing this, although it is |
| 46 | +/// occasionally necessary, especially with methods that return a generic type like `Into::into` or |
| 47 | +/// methods that don't take `self`. It's more common to use in macros where it can provide necessary |
| 48 | +/// hygiene. |
| 49 | +/// |
| 50 | +/// [^as-use-from]: You should probably never use this syntax with `Into` and instead write |
| 51 | +/// `T::from(my_thing)`. It just happens that there aren't any great examples for this syntax in |
| 52 | +/// the standard library. Also, at time of writing, the compiler tends to suggest fully-qualified |
| 53 | +/// paths to fix ambiguous `Into::into` calls, so the example should hopefully be familiar. |
| 54 | +/// |
| 55 | +/// For more information on what `as` is capable of, see the Reference on [type cast expressions] |
| 56 | +/// and [qualified paths]. |
| 57 | +/// |
| 58 | +/// [type cast expressions]: ../reference/expressions/operator-expr.html#type-cast-expressions |
| 59 | +/// [qualified paths]: ../reference/paths.html#qualified-paths |
43 | 60 | /// [`crate`]: keyword.crate.html |
44 | 61 | /// [`use`]: keyword.use.html |
45 | 62 | /// [const-cast]: pointer::cast |
|
0 commit comments