Rust HashMap Entry API: Lookup or Insert Efficiently

By the end of this page, you will understand why borrowing rules make the original match map.get(...) approach fail, and how Rust's HashMap::entry API solves the problem cleanly. You will learn how to look up a value, insert a default if missing, and get a reference or mutable reference in one efficient operation.

Rust prevents you from having an immutable borrow and a mutable borrow of the same value at the same time. In your original code, map.get(key) immutably borrows the HashMap, and inside the None branch you try to call map.insert(...), which needs a mutable borrow. That combination is not allowed.

This matters because Rust uses borrowing rules to prevent bugs like:

• reading stale references
• invalidating references after mutation
• data races in concurrent situations

For this exact pattern, Rust provides the Entry API on HashMap. The idea is simple:

• check whether a key exists
• if it exists, use the existing value
• if it does not exist, insert one
• return access to the value either way

This is both idiomatic and efficient because it avoids doing a separate contains_key and get lookup.

The most common methods are:

• entry(key) — access an entry for a key
• or_insert(value) — insert value if missing, otherwise return the existing one
• or_insert_with(|| ...) — compute the default only when needed

Think of a HashMap like a wall of lockers.

• get(key) means: "Open the building directory and look at locker key without changing anything."
• insert(key, value) means: "Possibly add or change a locker."

Rust does not let you say: "While I am still in read-only inspection mode, also modify the lockers." That is what your original code tries to do.

The entry API is like asking the building manager: "Give me the locker for this key. If it doesn't exist, create it first." You make one request, and the manager handles both cases safely.

Core syntax

use std::collections::HashMap;

let mut map: HashMap<&str, Vec<isize>> = HashMap::new();
let values = map.entry("foo").or_default();

values is a &mut Vec<isize> here. If the key exists, you get a mutable reference to the existing vector. If not, Rust inserts an empty vector and gives you a mutable reference to that.

Example: lookup or insert

use std::collections::HashMap;

fn main() {
    let mut map: HashMap<&str, Vec<isize>> = HashMap::new();

    let values: &mut Vec<isize> = map.entry("foo").or_default();
    values.push();
    values.();

    (, map);
}

Consider this code:

use std::collections::HashMap;

fn main() {
    let mut map: HashMap<&str, Vec<i32>> = HashMap::new();
    let key = "foo";

    let values = map.entry(key).or_default();
    values.push(5);
    values.push(8);

    println!("{:?}", map);
}

Step by step:

1. map starts empty.

   {}
   

2. map.entry(key) asks the map for the entry at "foo".

3. Since "foo" is not present, or_default() inserts Vec::default(), which is an empty vector.

This pattern appears constantly in real Rust programs.

Grouping items by key

use std::collections::HashMap;

let mut groups: HashMap<&str, Vec<i32>> = HashMap::new();

groups.entry("even").or_default().push(2);
groups.entry("even").or_default().push(4);
groups.entry("odd").or_default().push(3);

Useful for:

• categorizing data
• building indexes
• aggregating records

Counting occurrences

use std::collections::HashMap;

let words = ["cat", "dog", "cat"];
let mut counts: HashMap<&, > = HashMap::();

   words {
    *counts.(word).() += ;
}

In real projects, developers often use the entry API as the standard way to avoid double lookups and awkward borrow issues.

Common pattern: accumulate values

use std::collections::HashMap;

fn add_tag(map: &mut HashMap<String, Vec<String>>, user: String, tag: String) {
    map.entry(user).or_default().push(tag);
}

This is common in:

• request aggregation
• event grouping
• report generation

Common pattern: counters

use std::collections::HashMap;

fn count_event(counts: &mut HashMap<String, usize>, event: String) {
    *counts.entry(event).or_insert(0) += 1;
}

Guarding expensive construction

Use or_insert_with when creating the default is expensive:

1. Borrowing with get() and then trying to insert()

Broken code:

use std::collections::HashMap;

let mut map: HashMap<&str, Vec<i32>> = HashMap::new();
let key = "foo";

let values = match map.get(key) {
    Some(v) => v,
    None => {
        map.insert(key, Vec::new());
        map.get(key).unwrap()
    }
};

Why it fails:

• get() creates an immutable borrow
• insert() needs a mutable borrow
• both overlap in the match

Fix:

let values = map.(key).();

Quick reference

use std::collections::HashMap;

Insert if missing, then get mutable reference

let value = map.entry(key).or_default();

Insert a specific default

let value = map.entry(key).or_insert(Vec::new());

Insert using lazy construction

let value = map.entry(key).or_insert_with(Vec::new);

Count items

*map.entry(key).or_insert(0) += 1;

Group values

map.(key).().(item);

Why does map.get() followed by map.insert() fail in Rust?

Because get() immutably borrows the map, while insert() needs a mutable borrow. Rust does not allow those overlapping borrows.

What is the idiomatic Rust way to get-or-insert in a HashMap?

Use the entry API, usually with or_insert, or_insert_with, or or_default.

Should I use or_default() or or_insert(Vec::new())?

For a Vec, or_default() is usually cleaner and more idiomatic.

Does entry() do only one lookup?

Yes, that is one of its main benefits. It is designed for efficient get-or-insert behavior.

What type does or_default() return?

It returns &mut V, a mutable reference to the value in the map.

• HashMap::get — basic lookup that returns an optional shared reference.
• HashMap::get_mut — lookup when you need to modify an existing value.
• HashMap::entry — the core get-or-insert API for this problem.
• Option — get() returns Option, so understanding Some and None is essential.
• Borrowing and references — explains why immutable and mutable borrows cannot overlap.
• Ownership — helps explain why returning references to local temporaries is invalid.
• Default — useful because or_default() relies on the type's default value.
• Match expressions — relevant because the original code uses match, but borrow scopes matter.
• Closures — useful for or_insert_with(|| ...).
• Mutable references — important because or_insert and or_default return values.