Borrow

Recipe	Crates
Borrow Trait
Differences between Borrow, Deref, and AsRef in Generic Code
Implement Borrow for a Custom Type

Borrow Trait

Rust data types often have multiple representations to suit different needs. For example, smart pointer types like Box<T>↗ or Arc<T>↗ allow you to choose how a value is stored and managed. Some types, such as String↗, extend a more basic type (str↗) by adding features like mutability and dynamic growth, which require extra metadata. This design lets you use lightweight, immutable, borrowed types when possible, and switch to more flexible, feature-rich, memory-owning types when necessary. Common type pairs include:

Types express that they can be borrowed as some type T by implementing Borrow<T>↗. Use the trait's borrow method to return a reference &T. For instance, a Box<T> can be borrowed as &T, while a String can be borrowed as &str.

A type is free to borrow as several different types.

If a type wishes to mutably borrow as another type, allowing the underlying data to be modified, it can additionally implement the BorrowMut↗ trait.

With Borrow<T> and BorrowMut<T>, it is possible to write generic code that accept &T, and therefore works with both such owned and borrowed data. It is a form of trait-based polymorphism, which enables flexible APIs that accept multiple forms of a type.

Borrow is particularly useful when you are using (or implementing) a data structure, and you want to use either an owned or borrowed type as synonymous.

For example, as a data collection, HashMap<K, V> owns both keys and values. If the key's actual data is wrapped in a managing type of some kind, it should, however, still be possible to search for a value using a reference to the key's data. For instance, if the key is a string, then it is likely stored with the hash map as a String↗, while it should be possible to search using a &str↗. The Borrow trait enables this: you can insert with a String, but retrieve values using a &str reference, allowing for flexible and efficient key access without unnecessary allocations or conversions. Specifically, HashMap<K, V> functions like get accept &Q where K: Borrow<Q> and String is Borrow<str>:

use std::collections::HashMap;

// This is the most common use of `Borrow`.
// A `HashMap<String, V>` can be queried with a `&str`,
// because `String: Borrow<str>`.
fn main() {
    let mut scores: HashMap<String, u32> = HashMap::new();
    scores.insert("alice".to_string(), 10);
    scores.insert("bob".to_string(), 20);

    // Lookup with `&str` - no need to allocate a `String`:
    assert_eq!(scores.get("alice"), Some(&10));
    assert_eq!(scores.get("bob"), Some(&20));
}

You can, of course, write a generic function that accepts any type that can borrow as e.g. a string slice, be it String, &String, or &str, and use it in lookups seamlessly:

use std::borrow::Borrow;
use std::collections::HashMap;

fn find_score<K>(map: &HashMap<String, u32>, key: K) -> Option<u32>
where
    K: Borrow<str>,
{
    map.get(key.borrow()).copied()
}

fn main() {
    let mut scores = HashMap::new();
    scores.insert("eve".to_string(), 30);

    // Pass a `&str`.
    assert_eq!(find_score(&scores, "eve"), Some(30));

    // Pass a `String`.
    let name = "eve".to_string();
    assert_eq!(find_score(&scores, name), Some(30));
}

Implement Borrow for a Custom Type

You can implement Borrow↗ on your own types.

This said, BEWARE: Borrow is different from AsRef<T> in that Borrow is intended for equivalence - meaning the borrowed value should behave identically to the owned one. In particular, Eq, Ord and Hash must be equivalent for borrowed and owned values: x.borrow() == y.borrow() should give the same result as x == y:

mod cis {
    use std::borrow::Borrow;
    use std::convert::From;
    use std::hash::Hash;

    // Case-insensitive string.
    // Implement `Eq`, `PartialEq`, `Hash` (used by `HashMap`).
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct CaseInsensitiveString(String);

    impl From<String> for CaseInsensitiveString {
        fn from(s: String) -> Self {
            // We store the lowercase version of the string.
            Self(s.to_ascii_lowercase())
        }
    }

    // Equality with `str`, both ways:
    impl PartialEq<str> for CaseInsensitiveString {
        fn eq(&self, other: &str) -> bool {
            self.0.eq_ignore_ascii_case(other)
        }
    }

    impl PartialEq<CaseInsensitiveString> for str {
        fn eq(&self, other: &CaseInsensitiveString) -> bool {
            self.eq_ignore_ascii_case(&other.0)
        }
    }

    // Implement `Borrow<str>` to allow lookup.
    impl Borrow<str> for CaseInsensitiveString {
        fn borrow(&self) -> &str {
            &self.0
        }
    }
}

fn calculate_hash<T: std::hash::Hash>(t: &T) -> u64 {
    use std::hash::Hasher;
    let mut s = std::hash::DefaultHasher::new();
    t.hash(&mut s);
    s.finish()
}

fn main() {
    use std::borrow::Borrow;
    use std::collections::HashMap;

    use cis::CaseInsensitiveString;

    let x = CaseInsensitiveString::from("Hello".to_string());
    let y = CaseInsensitiveString::from("HELLO".to_string());

    assert!(x == *"heLLo");
    assert!(*"HellO" == y);

    // The `Borrow`-required invariants must hold:
    let xb: &str = x.borrow();
    let yb: &str = y.borrow();

    // - Equality holds:
    assert!(x == y);
    assert_eq!(xb, yb);

    // - Hashes are the same:
    assert_eq!(calculate_hash(&x), calculate_hash(&y));
    assert_eq!(calculate_hash(&xb), calculate_hash(&yb));

    // Conversely:
    let z = CaseInsensitiveString::from("World".to_string());
    let zb: &str = z.borrow();
    assert!(x != z);
    assert_ne!(calculate_hash(&x), calculate_hash(&z));
    assert!(xb != zb);
    assert_ne!(calculate_hash(&xb), calculate_hash(&zb));

    // Use the new `CaseInsensitiveString` type:
    let mut map: HashMap<CaseInsensitiveString, usize> = HashMap::new();
    map.insert(CaseInsensitiveString::from("HelLO".to_string()), 1);

    // Lookup with a (lowercase) `&str` thanks to `Borrow<str>`.
    if let Some(value) = map.get("hello") {
        println!("Found: {value}");
    } else {
        panic!("Not found.");
    }
}

Differences between Borrow, Deref, and AsRef in Generic Code

The Borrow↗ and AsRef↗ traits are very similar, but different in purposes.

• Use Borrow when you want to abstract over different kinds of borrowing, or when you're building a data structure that treats owned and borrowed values in equivalent ways, such as hashing and comparison.
• Use AsRef when you want to convert something to a reference directly or you're writing generic code.
• Deref↗ should be implemented by smart pointers only.

See AsRef, Conversion Traits and Smart Pointers for more details.

Related Topics

• AsRef.
• Conversion Traits.
• Ownership and Borrowing.