AsRef, Borrow y las conversiones ligeras: cuándo cada una

From e Into convierten valores que poseen su contenido y, al hacerlo, pueden asignar memoria. Pero con enorme frecuencia no quieres poseer nada: solo ver un valor como si fuera de otro tipo, a través de una referencia y sin coste —un &str a partir de un String, un &Path de un PathBuf, un &[T] de un Vec<T>—. Dos traits cubren ese hueco con firmas casi idénticas: AsRef y Borrow. Lo que los separa no es el código, que es el mismo, sino una ley. Y esa ley es exactamente lo que vuelve correcto consultar un HashMap<String, V> con un &str, sin asignar ni una copia.

AsRef: ver un valor como otro, sin coste

AsRef<T> ofrece un único método que convierte una referencia en otra, barata y sin asignar:

pub trait AsRef<T: ?Sized> {
    fn as_ref(&self) -> &T;
}

Su uso estelar es en firmas genéricas, para aceptar cualquier cosa que se pueda ver como el tipo que necesitas. La biblioteca lo emplea por todas partes: File::open recibe impl AsRef<Path>, y por eso le puedes pasar un &str, un String o un PathBuf indistintamente.

use std::path::Path;

fn componentes(ruta: impl AsRef<Path>) -> usize {
    ruta.as_ref().components().count()
}

fn main() {
    componentes("/etc/hosts");                     // &str
    componentes(String::from("/var/log"));         // String
    componentes(std::path::PathBuf::from("/tmp")); // PathBuf
    // los tres valen: los tres son AsRef<Path>
}

String: AsRef<str>, String: AsRef<[u8]>, Vec<T>: AsRef<[T]>, PathBuf: AsRef<Path>: la red de conversiones ligeras ya está tejida por ti.

Borrow: como AsRef, pero con una ley

Borrow<T> tiene una firma que, letra por letra, es la misma que la de AsRef:

pub trait Borrow<Borrowed: ?Sized> {
    fn borrow(&self) -> &Borrowed;
}

La diferencia no se ve en el tipo, sino en el contrato. Borrow exige que el valor prestado sea equivalente al dueño: que hashee igual, se compare igual y se ordene igual. AsRef no promete nada de eso; solo te da una vista barata. Por eso existe la implementación general Borrow<T> for T —todo valor se presta a sí mismo—, pensada para código genérico que quiere aceptar tanto un dueño como un préstamo con garantías de consistencia.

Por qué un HashMap de claves String se consulta con str

Aquí la ley cobra sentido práctico. La firma de get en los mapas es genérica sobre lo que le pasas a buscar:

// La firma que lo permite (esquematizada):
// fn get<Q>(&self, clave: &Q) -> Option<&V>
// where K: Borrow<Q>, Q: Hash + Eq + ?Sized

use std::collections::HashMap;

fn main() {
    let mut m: HashMap<String, i32> = HashMap::new();
    m.insert(String::from("uno"), 1);

    let v = m.get("uno");   // consulta con &str, no con &String
    assert_eq!(v, Some(&1));
}

Como String: Borrow<str> y la ley garantiza que un String y su &str producen el mismo hash y la misma igualdad, buscar con "uno" encuentra la clave guardada como String sin construir un String temporal. Si esto se apoyara en AsRef en vez de Borrow, nada impediría una conversión que cambiara el hash, y el mapa podría no encontrar una clave que “es igual” —un bug silencioso que la ley de Borrow diseña para que no exista—.

El mapa de las conversiones ligeras

Cuatro familias, dos ejes: ¿posees o prestas?, y ¿hay una ley o solo comodidad?

ToOwned es la dirección inversa de Borrow —de préstamo a valor poseído— y sostiene a Cow<'_, B> (clone on write), que presta mientras puede y solo asigna cuando de verdad tiene que modificar:

use std::borrow::Cow;

fn normaliza(entrada: &str) -> Cow<'_, str> {
    if entrada.contains(' ') {
        Cow::Owned(entrada.replace(' ', "_"))  // asigna solo si hace falta
    } else {
        Cow::Borrowed(entrada)                 // sin coste: presta
    }
}

flowchart TB
Q[Que conviertes] --> A[Valor a valor]
Q --> B[Referencia a referencia]
Q --> C[Referencia a valor]
A --> A1[From e Into puede asignar]
B --> B1[Necesitas la ley de igualdad]
B1 -->|si claves de mapa| BR[Borrow]
B1 -->|no solo ergonomia| AR[AsRef]
C --> C1[ToOwned generaliza Clone]
style BR fill:#a6e3a1,color:#11111b
style AR fill:#89b4fa,color:#11111b
style A1 fill:#cba6f7,color:#11111b
style C1 fill:#f9e2af,color:#11111b