diff options
| -rw-r--r-- | src/libcore/borrow.rs | 4 | ||||
| -rw-r--r-- | src/libcore/convert.rs | 10 |
2 files changed, 10 insertions, 4 deletions
diff --git a/src/libcore/borrow.rs b/src/libcore/borrow.rs index 89668dc0650..4d58aaca941 100644 --- a/src/libcore/borrow.rs +++ b/src/libcore/borrow.rs @@ -32,6 +32,10 @@ /// on the identical behavior of these additional trait implementations. /// These traits will likely appear as additional trait bounds. /// +/// In particular `Eq`, `Ord` and `Hash` must be equivalent for +/// borrowed and owned values: `x.borrow() == y.borrow()` should give the +/// same result as `x == y`. +/// /// If generic code merely needs to work for all types that can /// provide a reference to related type `T`, it is often better to use /// [`AsRef<T>`] as more types can safely implement it. diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index a6c65e890a5..7b9e19e36a2 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -105,11 +105,13 @@ pub const fn identity<T>(x: T) -> T { x } /// `&T` or write a custom function. /// /// -/// `AsRef` is very similar to, but serves a slightly different purpose than [`Borrow`]: +/// `AsRef` has the same signature as [`Borrow`], but `Borrow` is different in few aspects: /// -/// - Use `AsRef` when the goal is to simply convert into a reference -/// - Use `Borrow` when the goal is related to writing code that is agnostic to -/// the type of borrow and whether it is a reference or value +/// - Unlike `AsRef`, `Borrow` has a blanket impl for any `T`, and can be used to accept either +/// a reference or a value. +/// - `Borrow` also requires that `Hash`, `Eq` and `Ord` for borrowed value are +/// equivalent to those of the owned value. For this reason, if you want to +/// borrow only a single field of a struct you can implement `AsRef`, but not `Borrow`. /// /// [`Borrow`]: ../../std/borrow/trait.Borrow.html /// |