Contact Book

Store and search contacts using a HashMap, practicing ownership and borrowing as data moves between functions.

CollectionsOwnershipBorrowing

Overview

A contact book is a small enough project that its real subject is not the data itself but how Rust's borrow checker reacts to functions passing that data back and forth. Every contact will live in a HashMap<String, Contact> owned by one ContactBook struct, and every function that touches it — add, find, update, remove, search — will have to decide up front whether it needs to *read* the map (&HashMap), *change* the map (&mut HashMap), or *take ownership* of a value out of it entirely. Getting that decision right, and understanding why the compiler rejects the wrong one, is the actual point of this project.

By the end of this tutorial you will have a working contact book, and — deliberately — you will also have seen a borrow-checker error on purpose: a case where holding an immutable reference into the map and then trying to mutate the map at the same time does not compile. You will fix it, and in doing so you will understand one of the rules that makes Rust programs free of a whole category of bugs (dangling references, iterator invalidation) that are only caught at runtime, if at all, in most other languages.

What You'll Build

A Contact struct with name, phone, and email fields.
A ContactBook struct wrapping a HashMap<String, Contact> keyed by name.
add() and find() methods demonstrating ownership transfer versus borrowing.
An update() method that mutably borrows one entry without touching the rest of the map.
A deliberately broken snippet showing the classic "immutable + mutable borrow at once" compiler error, and its fix.
A search() method returning borrowed references to every contact matching a substring.

Prerequisites

Structs and basic methods in an impl block.
Ownership fundamentals — what "moving" a value means, and that a moved-from variable can no longer be used.
Borrowing — the difference between &T (shared/immutable) and &mut T (exclusive/mutable) references.
Option<T> — Some/None and unwrapping it safely with if let or match.
HashMap basics — insert(), get(), and iterating with .values() or .iter().

Project Structure

Create the project with cargo new contact_book and write everything in src/main.rs. Contact is a plain data struct with no methods of its own. ContactBook wraps a single HashMap<String, Contact> field and is the only type with methods on it — exactly the same "one owner, one set of methods" shape used by TaskManager in the CLI Task Manager project, just backed by a HashMap instead of a Vec because contacts are looked up by name, not by position.

The map is keyed by String, not &str — the map has to own its keys for as long as entries exist in it, and a borrowed &str tied to some caller's stack frame could not outlive the function call that inserted it. This is the same ownership reasoning that makes Task.description in the earlier project an owned String rather than a borrowed slice.

Step 1: Define the Contact Struct

Every field is an owned String. Deriving Clone is what makes it possible, later, to copy a Contact's data out of the map when you need a value that can outlive a borrow into the map — you will see exactly why that matters in Step 5.

// Every field is an owned String: a Contact must be able to outlive
// whatever &str a caller used to construct it, since it will be stored
// inside a HashMap that may live far longer than that call site.
#[derive(Debug, Clone)]
struct Contact {
    name: String,
    phone: String,
    email: String,
}

Step 2: Build a ContactBook Around a HashMap

ContactBook wraps one HashMap<String, Contact>. Rust's HashMap requires its key type to implement Eq and Hash, both of which String already implements, so no extra work is needed to use it as a key. HashMap::new(), like Vec::new(), allocates nothing until the first entry is inserted.

use std::collections::HashMap;

struct ContactBook {
    contacts: HashMap<String, Contact>,   // Keyed by contact name; String satisfies HashMap's Eq + Hash bound
}

impl ContactBook {
    fn new() -> ContactBook {
        ContactBook { contacts: HashMap::new() }
    }
}

Step 3: Add and Find Contacts

add() takes contact: Contact by value — ownership of the whole struct moves into the method, and then into the map via insert(). find() is where borrowing matters: it takes name: &str (borrowing the search key, not owning it) and returns Option<&Contact> — a borrowed reference to the contact still living inside the map, not a copy of it. That return type is the source of the pitfall in Step 5, so hold onto it.

impl ContactBook {
    // contact: Contact takes ownership -- the caller's Contact is moved in
    // here, then moved again into the HashMap by insert(). The caller has
    // no usable Contact left afterward, by design: the book is now the
    // sole owner of this data.
    fn add(&mut self, contact: Contact) {
        self.contacts.insert(contact.name.clone(), contact);   // clone() the key only; the Contact itself still moves whole
    }

    // &self (read-only borrow of the whole book) in, Option<&Contact> (a
    // borrow tied to that same book) out. No data is copied here at all.
    fn find(&self, name: &str) -> Option<&Contact> {
        self.contacts.get(name)
    }
}

Why contact.name.clone() as the key and not just contact.name? Because self.contacts.insert(key, contact) needs two separate values — the key String and the whole Contact (which also contains a name field) — and contact.name cannot be moved out of contact while contact itself is about to be moved into insert() as its second argument. Cloning the name is a small, deliberate cost that avoids fighting the borrow checker over a few bytes of duplicated text.

Example Usage

Click Run to see what this code prints.

Step 4: Update a Contact With a Mutable Borrow

update() uses get_mut() instead of get(), which returns Option<&mut Contact> — an exclusive, mutable borrow of just that one entry, not the whole map. While that &mut Contact is alive, the rest of ContactBook's methods are still perfectly usable on other data, because Rust's borrow checker tracks borrows at the granularity of the expression, not "the whole struct is locked." The Option<String> parameters let a caller update only the fields they actually want to change.

impl ContactBook {
    // new_phone/new_email are Option<String>: None means "leave this field
    // alone," letting a caller update just the phone, just the email, or
    // both, without three separate methods.
    fn update(&mut self, name: &str, new_phone: Option<String>, new_email: Option<String>) -> bool {
        match self.contacts.get_mut(name) {   // &mut Contact: exclusive access to this one entry only
            Some(contact) => {
                if let Some(phone) = new_phone {
                    contact.phone = phone;   // Overwrites the old String; the old value is dropped here
                }
                if let Some(email) = new_email {
                    contact.email = email;
                }
                true
            }
            None => false,   // No contact with that name; nothing to update
        }
    }
}

Step 5: An Ownership Pitfall: Borrowing Immutably and Mutably at Once

Here is code that looks reasonable and will not compile. find() returns an Option<&Contact> — an immutable borrow of book that, as far as the compiler is concerned, stays alive for as long as contact is still going to be used later in the block. Calling book.remove(...) (Step 6) needs a *mutable* borrow of the same book, and Rust's one rule for references is simple: you may have either any number of shared & borrows, or exactly one exclusive &mut borrow, never both at the same time.

// This will NOT compile:
if let Some(contact) = book.find("Asha Rao") {
    book.remove("Asha Rao");                 // ERROR: cannot borrow `book` as mutable
                                               // because it is also borrowed as immutable
    println!("Removed: {}", contact.name);   // `contact` is still "in use" here
}

This is not the compiler being overcautious. If it allowed this, remove() could drop the Contact from the HashMap while contact still pointed at where that entry used to live — exactly the dangling-pointer bug that crashes or silently corrupts memory in a language without a borrow checker. Rust catches it at compile time instead, before the program ever runs.

The fix is to decide what you actually need from contact while the immutable borrow is alive, pull that out as an owned value (with .clone()), and let the borrow end before calling anything that needs &mut book. Because Rust uses non-lexical lifetimes, a borrow's scope ends at its last use, not at the closing brace of the block it was created in — so simply reordering the code so the mutation happens after the last read is enough.

// Fixed: clone what we need out of the immutable borrow, which ends the
// borrow at its last use (Rust's non-lexical lifetimes) -- so by the time
// remove() runs, no outstanding &Contact into `book` exists anymore.
let removed_name = match book.find("Asha Rao") {
    Some(contact) => Some(contact.name.clone()),   // Clone just the field we need; `contact` isn't used again after this
    None => None,
};

if let Some(name) = removed_name {
    book.remove(&name);                              // Safe now: the earlier immutable borrow already ended
    println!("Removed: {name}");
}

Step 6: Remove a Contact and Search by Substring

remove() uses HashMap::remove(), which returns Option<Contact> — ownership of the removed value, handed back to the caller (or None if the key was not present). search() borrows the whole map with .values() (an iterator of &Contact) and filters with .contains(), collecting the surviving borrows into a Vec<&Contact>; nothing is cloned, because the caller only needs to read the matches, not keep them past the search call.

impl ContactBook {
    fn remove(&mut self, name: &str) -> Option<Contact> {
        self.contacts.remove(name)   // Returns the owned Contact that was removed, or None if it wasn't there
    }

    // Returns borrowed references (Vec<&Contact>), not clones -- the caller
    // only needs to read the matches, so there's no reason to copy every
    // matching Contact's data just to print it.
    fn search(&self, query: &str) -> Vec<&Contact> {
        let query_lower = query.to_lowercase();
        self.contacts
            .values()                                                     // Iterator<Item = &Contact>
            .filter(|c| c.name.to_lowercase().contains(&query_lower))   // Keep only case-insensitive substring matches
            .collect()
    }
}

Step 7: Build the Menu Loop

The menu loop applies the fix from Step 5 directly: the remove branch reads user input for a name, then calls book.remove(&name) in one step, with no lingering find() borrow held across it. Every other branch follows the same shape as the earlier projects in this course — read a line, trim it, act on it.

use std::io::{self, Write};

fn main() {
    let mut book = ContactBook::new();

    loop {
        println!("\n===== CONTACT BOOK =====");
        println!("1. Add Contact");
        println!("2. Find Contact");
        println!("3. Update Contact");
        println!("4. Remove Contact");
        println!("5. Search Contacts");
        println!("6. Exit");
        print!("Enter your choice: ");
        io::stdout().flush().unwrap();

        let mut choice = String::new();
        io::stdin().read_line(&mut choice).expect("failed to read input");

        match choice.trim() {
            "1" => {
                let name = read_line("Enter name: ");
                let phone = read_line("Enter phone: ");
                let email = read_line("Enter email: ");
                book.add(Contact { name, phone, email });
                println!("Contact added.");
            }
            "2" => {
                let name = read_line("Enter name to find: ");
                match book.find(&name) {
                    Some(c) => println!("{} | {} | {}", c.name, c.phone, c.email),
                    None => println!("No contact with that name."),
                }
            }
            "3" => {
                let name = read_line("Enter name to update: ");
                let phone = read_line("Enter new phone (blank to keep): ");
                let email = read_line("Enter new email (blank to keep): ");
                let phone = if phone.is_empty() { None } else { Some(phone) };
                let email = if email.is_empty() { None } else { Some(email) };
                if book.update(&name, phone, email) {
                    println!("Contact updated.");
                } else {
                    println!("No contact with that name.");
                }
            }
            "4" => {
                let name = read_line("Enter name to remove: ");
                match book.remove(&name) {   // No earlier find() borrow held across this call -- safe by construction
                    Some(_) => println!("Removed."),
                    None => println!("No contact with that name."),
                }
            }
            "5" => {
                let query = read_line("Enter search text: ");
                let results = book.search(&query);
                if results.is_empty() {
                    println!("No matches.");
                } else {
                    for c in results {
                        println!("{} | {} | {}", c.name, c.phone, c.email);
                    }
                }
            }
            "6" => {
                println!("Goodbye!");
                break;
            }
            _ => println!("Invalid choice, try again."),
        }
    }
}

// Small helper shared by every menu branch above that needs one line of
// text input -- avoids repeating the same print!/flush/read_line/trim
// sequence five separate times.
fn read_line(prompt: &str) -> String {
    print!("{prompt}");
    io::stdout().flush().unwrap();
    let mut input = String::new();
    io::stdin().read_line(&mut input).expect("failed to read input");
    input.trim().to_string()
}

Complete Code

Here is the full program assembled in the correct order, ready to save as src/main.rs and run with cargo run.

use std::collections::HashMap;
use std::io::{self, Write};

#[derive(Debug, Clone)]
struct Contact {
    name: String,
    phone: String,
    email: String,
}

struct ContactBook {
    contacts: HashMap<String, Contact>,
}

impl ContactBook {
    fn new() -> ContactBook {
        ContactBook { contacts: HashMap::new() }
    }

    fn add(&mut self, contact: Contact) {
        self.contacts.insert(contact.name.clone(), contact);
    }

    fn find(&self, name: &str) -> Option<&Contact> {
        self.contacts.get(name)
    }

    fn update(&mut self, name: &str, new_phone: Option<String>, new_email: Option<String>) -> bool {
        match self.contacts.get_mut(name) {
            Some(contact) => {
                if let Some(phone) = new_phone {
                    contact.phone = phone;
                }
                if let Some(email) = new_email {
                    contact.email = email;
                }
                true
            }
            None => false,
        }
    }

    fn remove(&mut self, name: &str) -> Option<Contact> {
        self.contacts.remove(name)
    }

    fn search(&self, query: &str) -> Vec<&Contact> {
        let query_lower = query.to_lowercase();
        self.contacts
            .values()
            .filter(|c| c.name.to_lowercase().contains(&query_lower))
            .collect()
    }
}

fn read_line(prompt: &str) -> String {
    print!("{prompt}");
    io::stdout().flush().unwrap();
    let mut input = String::new();
    io::stdin().read_line(&mut input).expect("failed to read input");
    input.trim().to_string()
}

fn main() {
    let mut book = ContactBook::new();

    loop {
        println!("\n===== CONTACT BOOK =====");
        println!("1. Add Contact");
        println!("2. Find Contact");
        println!("3. Update Contact");
        println!("4. Remove Contact");
        println!("5. Search Contacts");
        println!("6. Exit");
        print!("Enter your choice: ");
        io::stdout().flush().unwrap();

        let mut choice = String::new();
        io::stdin().read_line(&mut choice).expect("failed to read input");

        match choice.trim() {
            "1" => {
                let name = read_line("Enter name: ");
                let phone = read_line("Enter phone: ");
                let email = read_line("Enter email: ");
                book.add(Contact { name, phone, email });
                println!("Contact added.");
            }
            "2" => {
                let name = read_line("Enter name to find: ");
                match book.find(&name) {
                    Some(c) => println!("{} | {} | {}", c.name, c.phone, c.email),
                    None => println!("No contact with that name."),
                }
            }
            "3" => {
                let name = read_line("Enter name to update: ");
                let phone = read_line("Enter new phone (blank to keep): ");
                let email = read_line("Enter new email (blank to keep): ");
                let phone = if phone.is_empty() { None } else { Some(phone) };
                let email = if email.is_empty() { None } else { Some(email) };
                if book.update(&name, phone, email) {
                    println!("Contact updated.");
                } else {
                    println!("No contact with that name.");
                }
            }
            "4" => {
                let name = read_line("Enter name to remove: ");
                match book.remove(&name) {
                    Some(_) => println!("Removed."),
                    None => println!("No contact with that name."),
                }
            }
            "5" => {
                let query = read_line("Enter search text: ");
                let results = book.search(&query);
                if results.is_empty() {
                    println!("No matches.");
                } else {
                    for c in results {
                        println!("{} | {} | {}", c.name, c.phone, c.email);
                    }
                }
            }
            "6" => {
                println!("Goodbye!");
                break;
            }
            _ => println!("Invalid choice, try again."),
        }
    }
}

Sample Run

Click Run to see what this code prints.

Extend This Project

Add a Vec<String> of tags per Contact and a find_by_tag() search over them.
Persist the HashMap to a file (JSON via serde_json, or a simple |-delimited format like the CLI Task Manager project) so contacts survive between runs.
Return Result<(), String> from add() instead of silently overwriting an existing contact with the same name.
Add a merge(&mut self, other: ContactBook) method that takes ownership of another book's contacts and folds them into this one.
Switch search() to also match on phone and email, not just name.

Summary

You built a contact book where every method's signature — &self, &mut self, or an owned parameter — is a deliberate statement about whether that operation reads, mutates, or takes ownership of data. More importantly, you hit a real borrow-checker error on purpose in Step 5 and fixed it by cloning out exactly the data you needed before mutating, which is the standard escape hatch whenever an immutable borrow and a mutation of the same value would otherwise overlap. That instinct — "what do I actually need to keep, and can I own a small copy of it instead of holding a reference across a mutation" — is one of the most useful habits you can build as a working Rust programmer.