Better ergonomics for WorldBorrow[Mut] API

[ruifengx]

Objective

• Allow mapping a WorldBorrow[Mut]<T> to WorldBorrow[Mut]<U>
• Allow cloning a WorldBorrow<T>

Consider the following example:

#[derive(Resource)]
struct SomeResource {
    some_field: Vec<u32>,
    some_other_field: Option<Vec<u32>>,
}

pub fn get_global_some_field(world: &WorldCell) -> Option<WorldBorrow<[u32]>> {
    Some(world.resource::<SomeResource>()?.map(|res| &res.some_field))
}

pub fn get_global_some_other_field(world: &WorldCell) -> Option<WorldBorrow<[u32]>> {
    Some(world.resource::<SomeResource>()?.try_map(|res| res.some_field.as_ref())?)
}

Previously it is very complicated to define the two accessor functions, because &[u32] must outlive the WorldBorrow<SomeResource>, and we have to e.g. return a wrapper around WorldBorrow<SomeResource> implementing Deref<[u16]>.

Now that we have two functions consuming WorldBorrows, it might also be desirable to keep the original borrow by cloning it beforehand. Therefore we implement Clone for WorldBorrow<T>.

Solution

• map and try_map consumes self and moves the witness of borrow.
• clone simply borrows the data again from the same world.

Unresolved Questions

• map and try_map are introduced as functions instead of inherent methods
  • Official Guideline: https://rust-lang.github.io/api-guidelines/predictability.html#smart-pointers-do-not-add-inherent-methods-c-smart-ptr
  • But Mut::map_unchanged is already an inherent method, so there is an inconsistency

---

Changelog

• Add map and try_map for WorldBorrow and WorldBorrowMut
• Implement Clone for WorldBorrow
  Technically this will break downstream code because borrow.clone() is now ambiguous

Migration Guide

WorldBorrow<T> now implements Clone. If you have code cloning the inner value behind a WorldBorrow:

let borrow: WorldBorrow<T>;
let cloned = borrow.clone(); // T

You need to explicitly dereference the borrow to clone the inner value:

let t_cloned = T::clone(&borrow); // or
let t_cloned = (*borrow).clone();

Now you may also clone the borrow itself:

let borrow_cloned = borrow.clone(); // or
let borrow_cloned = WorldBorrow::clone(&borrow);

[ItsDoot]

WorldCell was removed in #12551, visit the linked PR for the rationale.