Add LruCache::sparse()

[drbrain]

I have a use case where I want to create many large-capacity LRUs where typical behavior is the LRU is not necessary. LruCache::new() allocates a HashMap with a capacity matching the LRU capacity and I don't have PB of RAM that will not store LRU entries.

I currently use this workaround:

let mut lru = LruCache::new(NonZeroUsize::new(1).unwrap());
lru.resize(NonZeroUsize::new(actual_capacity).unwrap());

But I worry that a future change to LruCache::resize() will use HashMap::reserve(), expanding memory usage, and invalidate my workaround.

[Copilot]

🟡 Changes recommended

The new API should clarify its allocation semantics in the docs to avoid implying it performs zero allocations.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a new constructor to create large-capacity LruCaches without the upfront HashMap pre-allocation that LruCache::new() performs, addressing memory usage for workloads where caches are often mostly empty.

Changes:

• Added LruCache::sparse(cap) constructor that builds the cache with an empty backing map instead of with_capacity(cap.get()).
• Added API documentation and an example for the new constructor.

File summaries

File	Description
src/lib.rs	Adds LruCache::sparse() to avoid pre-allocating the backing HashMap for large capacities.

Review details

Suppressed comments (1)

src/lib.rs:247

• sparse() solves the large-capacity preallocation problem for the default hasher, but with_hasher() still pre-allocates based on cap. For API completeness (and to support custom hashers in no-std / deterministic hashing use cases), consider adding a sparse_with_hasher(cap, hash_builder) constructor that does not pre-allocate.

    pub fn sparse(cap: NonZeroUsize) -> LruCache<K, V> {
        LruCache::construct(cap, HashMap::default())
    }

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[drbrain]

It seems one other PR is also failing on beta and nightly so I guess I don't need to worry about those?

[jeromefroe]

LGTM, thank you for the contribution @drbrain. I'll merge since CI is failing for an unrelated reason that was fixed on the master branch earlier.