From 1cfed0d452d739b502c73904d61a1f4496b1acf5 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Wed, 3 Apr 2019 11:19:16 +0300 Subject: [PATCH] be more direct about borrow requirenments --- src/libcore/borrow.rs | 4 ++++ 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 89668dc06505b..4d58aaca94183 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`] as more types can safely implement it. diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index a6c65e890a5ed..7b9e19e36a293 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -105,11 +105,13 @@ pub const fn identity(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 ///