libs: Add borrow module, deprecate _equiv and friends

[aturon]

Following the collections reform RFC, this PR:

• Adds a new borrow module to libcore. The module contains traits for borrowing data (BorrowFrom and BorrowFromMut), generalized cloning (ToOwned), and a clone-on-write smartpointer (Cow).
• Deprecates the _equiv family of methods on HashMap and HashSet by instead generalizing the "normal" methods like get and remove to use the new std::borrow infrastructure.
• Generalizes TreeMap, TreeSet, BTreeMap and BTreeSet to use the new std::borrow infrastructure for lookups.

[breaking-change]

[aturon]

cc #18424
cc @Gankro

[aturon]

Note that the design here is somewhat different than the one in the RFC. This was necessary in order to overcome some language limitations: using Borrow instead of BorrowFrom requires full method-level where clauses, which are not yet available.

This will be noted in the tracking issue, and made part of a general amendment to the RFC with implementation tweaks.

[aturon]

Also, the deprecation of MaybeOwned in favor of Cow will be left for follow-up work.

[nikomatsakis]

Nifty.

[aturon]

Another note: the RFC did not mention generalizing the indexing notation using the borrow traits, but of course that only makes sense. This PR does that as well. (Thanks @nikomatsakis for pointing out that it should.)

[alexcrichton]

This is an interesting stylistic precedent to line up the where and fn keywords, I would have expected the alignment of where to match the alignment of -> if it came on the next line which I thought was the ( in the argument list.

[aturon]

Yeah, I know :-) generally we need to actually firm up all our style conventions, but that's of course lower priority than API issues. I'm happy to go with your recommended style here.

[Gankro]

Personally I'd just do a double-indent, like a normal line continuation.

[alexcrichton]

These diffs make me happy.

[alexcrichton]

Is there a reason you chose BorrowFrom{,Mut} instead of Borrow{,Mut}? (like in the RFC)

[Gankro]

Should these be in vec.rs? Genuinely unsure.

[Thiez]

Since the BorrowFrom and BorrowFromMut traits are in libcore, they cannot implement for Vec there. Sincce these implementations can't be anywhere else, surely this is the right place?

[aturon]

They could be in the vec module in libcollections. I put them here because they are being applied to the slice type, and I feel like putting impls in the module defining their Self type is a good default.

[nikomatsakis]

@aturon it occurs to me that we may be able to implement PathBuf : BorrowFrom<Path> and thus have a hashmap keyed on PathBuf be indexable with a Path. The blanket impl wouldn't conflict because it requires that the two types be equal, and PathBuf != Path. I'm not sure how it would interact with inference.

[Gankro]

s/contruct/construct

[Gankro]

It seems weird to duplicate the trait and enum definitions in the docs themselves?

[Gankro]

s/type/time

[Gankro]

Any reason to use Owned here and T in the impl?

[Gankro]

Do we want people to be able to match on the internals of this?

[aturon]

I debated making this a newtype. That's probably the more conservative thing to do, but then we'd need to separately expose constructors. Either way is fine by me.

[Gankro]

Hmm... unsure. I feel like newtyping is "the right thing", but I dunno. It's unstable so I think we can leave it like this for now, and revisit this for stabilization.

[aturon]

@alexcrichton Note the comments above re: differences from the RFC.

[aturon]

@nikomatsakis

@aturon it occurs to me that we may be able to implement PathBuf : BorrowFrom<Path> and thus have a hashmap keyed on PathBuf be indexable with a Path. The blanket impl wouldn't conflict because it requires that the two types be equal, and PathBuf != Path. I'm not sure how it would interact with inference.

Yes! That's very much the plan. Note that the blanket impl implicitly requires sized types, which is enough to avoid the overlap.

[Gankro]

What is this necessary for?

[gereeter]

This allows you to use things like HashMap<&'static str, T> effectively. However, I don't see any reason to not generalize this to impl<'a, Sized? T> BorrowFrom<&'a T> for T.

[gereeter]

Note: there was an issue a while ago (that I just spent far too long failing to find) about the fact that there was no good way to use data structures keyed on reference types like &'static str.

[Gankro]

Any reason to make this public?

[aturon]

Yes. This gives you a mutable reference to the owned type, not the borrowed type, which you can't get otherwise -- and does so without destroying the Cow pointer itself.

[SimonSapin]

Doesn't deref_mut do the same?

[aturon]

No, the types are different. deref_mut gives you &mut Borrowed, this gives you &mut Owned.

[aturon]

And there's no way to change deref_mut to give you this type, because it must yield the same underlying type as deref does, which we definitely want to be borrowed (since we don't want it to require an owned copy).

[Gankro]

\o/ This is wonderful! 😍

[gereeter]

I know that the RFC said to use T: Sized here to prevent overlap with the other impls, but now that we have multidispatch this shouldn't be a problem, right?

[gereeter]

This breaks the alignment of the arguments. Should they be realigned?

[Gankro]

You seem to have forgotten btree.

[Gankro]

Possible thing to include: tuple of Owned -> tuple of Borrowed impls.

[SimonSapin]

If I understand correctly, this assumes that the implementations of Hash and Eq for Q and K are compatible, right? That is, for any k1 and k2 of type K:

let q1: Q = BorrowFrom::borrow_from(k1);
let q2: Q = BorrowFrom::borrow_from(k2);
assert_eq!(make_hash(q1), make_hash(k1));
assert_eq!(q1 == q2, k1 == k2);

That invariant unfortunately doesn’t seem like it can be enforced by the type system, but maybe it should be documented?

The problem was the same with Equiv. We ran into it in Servo when trying to make hashing of interned strings O(1) by only hashing the internal u64.

[aturon]

Yes, this was a tradeoff brought up in the RFC. It's possible to enforce this invariant, but at some loss in flexibility: it would force you to consistently use a single kind of borrowed value for lookups.

Agreed about documentation.

[aturon]

@Gankro @alexcrichton

Pushed a new version; I believe I've addressed all comments.

[pythonesque]

Any way Cow could not be done through deref(mut)? It was pointed out on IRC that this would be Rust's first "costly" use of those traits, which at least to me seems like it's sufficient to negate the syntactic simplicity of magic.

[alexcrichton]

@thestinger with rust-lang/rfcs#439 we'll have a trait definition that looks like:

pub trait Ord<Rhs = Self>: Eq<Rhs> + PartialOrd<Rhs> {
    fn cmp(&self, other: &Rhs) -> Ordering;
}

in which case I think we can leverage the Rhs type parameter to compare any type to the key type:

impl<K, V> TreeMap<K, V> {
    fn get<Q>(&self, q: &Q) -> Option<&V> where K: Ord<Q> { /* ... */ }
}

impl<T, U: BorrowFrom<T>> Ord<U> for T { /* ... */ }

I'm not entirely sure how much coherence would disallow, but it seems like it should be possible.

[aturon]

@pythonesque yes, you're right, supporting DerefMut here does not fit will with our general strategy of making things like clone explicit. (Deref is fine.) I will revise.

[aturon]

@pythonesque I've removed the DerefMut impl.

@thestinger I reinstated the find_with methods as #[experimental]; I have no objection to keeping them around under that status for now.

@alexcrichton re-r?

[thestinger]

@aturon: Thanks, I'm in full agreement with this pull request then.

[TeXitoi]

Why to_owned must takes a reference?

I think that HashMap::entry() can take a ToOwned<K> as key, and create a owned object if needed. But to have that to work, we should have to_owned taking self to allow T: ToOwned<T> to just move.

Example: http://is.gd/YORUei

I didn't tried to modify this pull request with this change, so maybe there is problem in Cow with this change.

[aturon]

r=alexcrichton