.borrow() on Builders collides badly with std::borrow::Borrow

[sdleffler]

Hey folks! I've been writing a library which uses capnp and also does some nifty stuff with the std::borrow::Borrow trait, which has this method Borrow::borrow. I imported Borrow::borrow at the top of my file and it caused majorly confusing issues with capnp; to make a long story short, for everything I wrote with capnp which was building an object (and using Builder::borrow) Rust attempted to resolve the methods as Borrow::borrow instead. This resulted in extremely confusing errors such as "attempt to move out of borrowed content" on calling builder.borrow().get_field(). I realize it's not possible to reimplement borrow in terms of the Borrow trait, but it's currently extremely bad trying to use std::borrow::Borrow; at the top of a file and also do something with Builder which requires Builder::borrow. I've localized all my use statements for Borrow::borrow and it's quite nasty.

I realize a name change would unfortunately be a pretty bad breaking change, but I just want to put the possibility out there. Colliding with a useful, bread-and-butter (for me, at least) stdlib trait in this nasty way seems Not Good. I don't really have any other solutions to suggest though.

[dwrensha]

Looks like we're colliding with impl<'a, T: ?Sized> Borrow<T> for &'a T. My understanding is that rustc usually prefers an inherent method over a trait method, but unfortunately in this case the trait method wins because it doesn't need a deref conversion. The rules are documented here: https://github.com/rust-lang-nursery/reference/blob/86b7c821e16c9e3e78897d6193314ca88a87e2f1/src/expressions/method-call-expr.md

Probably reborrow() would be a better name for our inherent method.

Note that there has been some discussion about adding reborrow support to the language: rust-lang/rfcs#1403

[dwrensha]

I've opened a pull request that deprecate borrow() in favor of reborrow(): #91

The new method name is slightly longer, which could potentially be annoying, but I think that the disambiguation is worth it.

@sdleffler please let me know if you have any further thoughts or opinions!