`Ref` Wrapper API

[ibraheemdev]

It is sometimes useful to wrap a Guard and a &V into a single type instead of requiring a Guard as input. We could add a Ref wrapper type to support this. See the advanced lifetimes guide for context.

I'm unsure how the API should look as I don't want this to be the default return type for get. We could potentially add a Ref::create method that takes a guard and a closure that creates a value tied to the guard and extends the lifetime. However, we have to be careful about not creating self references. Though this is unlikely, it would be possible to create a HashMap<K, &Guard> or similar through Ref::create, so we might have to unfortunately restrict it to 'static types.

[XAMPPRocky]

FWIW after having used papaya a little bit and encountering this need, I think the intuitive solution would be to add a HashMap::pin_ref method which returns a wrapper around HashMapRef which implements the same methods but returns the Ref type.

This has benefit of only adding one "new" method, and allowing the rest of the API surface to look the same e.g.

map.pin_ref().get("foo")

map.pin().get_ref("foo")

let pin = map.pin();
Ref::create(pin.get("foo"), pin)

[ibraheemdev]

Yeah that could work. I was envisioning an API something like map.create_ref(|m| m.get("foo")) to avoid duplicating the entire API on a wrapper type.