Skip to content

Commit 15f73ab

Browse files
committed
Document fully-qualified syntax in as' keyword doc
1 parent 55d4364 commit 15f73ab

File tree

1 file changed

+14
-0
lines changed

1 file changed

+14
-0
lines changed

library/std/src/keyword_docs.rs

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,20 @@
2424
/// (`u8`, `bool`, `str`, pointers, ...) whereas `From` and `Into` also works with types like
2525
/// `String` or `Vec`.
2626
///
27+
/// You'll also find with `From` and `Into`, and indeed all traits, that `as` is used for the
28+
/// _fully qualified path_, a means of clarifying ambiguous associated items, i.e. functions,
29+
/// constants, and types. For example, if you have a type which implements two traits with identical
30+
/// method names (e.g. `Into::<u32>::into` and `Into::<u64>::into`), you can clarify which method
31+
/// you'll use with `<MyThing as Into<u32>>::into(my_thing)`[^as-use-from]. This is quite verbose,
32+
/// but fortunately, Rust's type inference usually saves you from needing this, although it is
33+
/// occasionally necessary, especially with methods that return a generic type like `Into::into` or
34+
/// static methods. It's more common to use in macros where it can provide necessary hygeine.
35+
///
36+
/// [^as-use-from]: You should probably never use this syntax with `Into` and instead write
37+
/// `T::from(my_thing)`. It just happens that there aren't any great examples for this syntax in
38+
/// the standard library. Also, at time of writing, the compiler tends to suggest fully-qualified
39+
/// paths to fix ambiguous `Into::into` calls, so the example should hopefully be familiar.
40+
///
2741
/// `as` can also be used with the `_` placeholder when the destination type can be inferred. Note
2842
/// that this can cause inference breakage and usually such code should use an explicit type for
2943
/// both clarity and stability. This is most useful when converting pointers using `as *const _` or

0 commit comments

Comments
 (0)