Rust Series : Borrow Checker as Design Partner - Understanding Lifetimes Through Analogies

fn main() {
    // This is our complete program demonstrating basic lifetime concepts

    // CONCEPT: Owner and Borrower relationship
    // The apartment owner has full control of the data
    let apartment = String::from("Luxury Penthouse"); // Owner of the data

    // CONCEPT: Borrowing creates a lease contract
    // The borrower gets access but not ownership
    let lease = &apartment; // Borrower signs a read-only lease

    // CONCEPT: Using borrowed data
    // While the lease is active, we can use the data
    println!("Living in: {}", lease);

    // CONCEPT: Lease duration
    // The lease automatically expires when `lease` goes out of scope
    // The apartment owner retains full ownership

    println!("Owner still has: {}", apartment);

    // CONCEPT: Why this is safe
    // The borrow checker ensures:
    // 1. We can't use `lease` after it expires
    // 2. The `apartment` can't be destroyed while `lease` exists
    // 3. No memory safety issues possible

    demonstrate_multiple_leases();
    demonstrate_mutable_lease();
    demonstrate_lease_conflicts();
}

fn demonstrate_multiple_leases() {
    println!("\n--- Multiple Read-Only Leases ---");

    // CONCEPT: Multiple read-only borrows are allowed
    // Think of this like multiple tourists visiting a building
    let building = vec![1, 2, 3, 4, 5]; // Owner

    // Multiple visitors can look at the building simultaneously
    let visitor1 = &building; // First tourist
    let visitor2 = &building; // Second tourist  
    let visitor3 = &building; // Third tourist

    // All visitors can observe the building at the same time
    println!("Visitor 1 sees: {:?}", visitor1);
    println!("Visitor 2 sees: {:?}", visitor2);
    println!("Visitor 3 sees: {:?}", visitor3);

    // CONCEPT: Why this works
    // Read-only access is safe because:
    // 1. No one is modifying the data
    // 2. Multiple readers can't cause data races
    // 3. The original owner retains ownership
}

fn demonstrate_mutable_lease() {
    println!("\n--- Mutable Lease (Renovation Contract) ---");

    // CONCEPT: Mutable borrowing is like exclusive renovation rights
    let mut building = vec![1, 2, 3]; // Owner who allows modifications

    // CONCEPT: Scope-based lease management
    // We use a scope to clearly show when the renovation lease is active
    {
        // The renovator gets exclusive access to modify the building
        let renovator = &mut building; // Exclusive modification lease

        // Only the renovator can make changes during their lease period
        renovator.push(4); // Adding a new room
        renovator.push(5); // Adding another room

        println!("Renovator's progress: {:?}", renovator);

        // CONCEPT: Exclusive access
        // While renovator has the lease, no one else can access the building
        // This prevents data races and ensures safety

    } // Renovator's lease expires here

    // CONCEPT: Lease expiration
    // Now the owner can access their property again
    println!("Building after renovation: {:?}", building);

    // CONCEPT: Sequential access
    // We can create a new lease after the previous one expires
    {
        let inspector = &building; // New read-only lease
        println!("Inspector's report: {:?}", inspector);
    } // Inspector's lease expires
}

fn demonstrate_lease_conflicts() {
    println!("\n--- Lease Conflicts (What the Borrow Checker Prevents) ---");

    let mut kitchen = vec!["flour", "eggs", "milk"];

    // CONCEPT: Why simultaneous mutable and immutable borrows are forbidden
    // This would be like having a chef cooking while health inspectors are present

    let chef = &mut kitchen; // Chef gets exclusive kitchen access
    chef.push("sugar"); // Chef is actively cooking

    // UNCOMMENT THE NEXT LINE TO SEE THE BORROW CHECKER IN ACTION:
    // let inspector = &kitchen; // ERROR! Can't inspect while chef is cooking
    // println!("Inspector sees: {:?}", inspector);

    println!("Chef's kitchen: {:?}", chef);

    // CONCEPT: Sequential access is safe
    // After the chef finishes (chef goes out of scope), inspector can enter

    // Chef's exclusive access ends here when `chef` goes out of scope
    let inspector = &kitchen; // Now inspector can safely observe
    println!("Inspector's report: {:?}", inspector);

    // CONCEPT: The borrow checker's wisdom
    // This prevents:
    // 1. Data races (simultaneous read/write)
    // 2. Use-after-free bugs
    // 3. Iterator invalidation
    // 4. Memory corruption
}

// CONCEPT: Function parameters and lifetimes
// This function demonstrates how lifetimes work across function boundaries
fn analyze_apartment(description: &str) -> &str {
    // CONCEPT: Lifetime elision in action
    // The compiler automatically infers that the output lifetime
    // is tied to the input lifetime

    // We're returning a slice of the input string
    // The borrow checker ensures the input lives long enough
    if description.len() > 10 {
        &description[0..10] // Return first 10 characters
    } else {
        description // Return the whole string
    }
}

// CONCEPT: Lifetime annotations made explicit
// This is what the compiler infers for the function above
fn analyze_apartment_explicit<'a>(description: &'a str) -> &'a str {
    // The 'a lifetime parameter says:
    // "The output reference lives as long as the input reference"
    // This creates a contract that the borrow checker enforces

    if description.len() > 10 {
        &description[0..10]
    } else {
        description
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_lease_safety() {
        // CONCEPT: Testing lifetime safety
        let data = String::from("test apartment");
        let result = analyze_apartment(&data);

        // Both data and result are valid here
        assert_eq!(result, "test apart");

        // CONCEPT: The borrow checker ensures this test is memory-safe
        // The `data` lives long enough for `result` to be valid
    }

    #[test]
    fn test_multiple_borrows() {
        let building = vec![1, 2, 3];
        let view1 = &building;
        let view2 = &building;

        // Multiple read-only views are safe
        assert_eq!(view1.len(), 3);
        assert_eq!(view2.len(), 3);
    }
}