Simple Cacher
A high-performance, flexible caching library for Rust with custom matching capabilities and automatic expiration.
Features
- Fast O(1) exact key lookups using IndexMap
- Custom pattern matching via the
Matcher<T>trait - Automatic expiration with configurable TTL per entry
- Size-limited caches with FIFO eviction (oldest entries removed first)
- Lazy cleanup - expired entries removed on access
- Zero-copy value access through references
- Thread-safe design (when used with appropriate synchronization)
- Comprehensive error handling
Installation
Add this to your Cargo.toml:
[]
= "0.1.0"
# Optional: Enable regex support
= { = "0.1.0", = ["regex_support"] }
Quick Start
use *;
use Duration;
// Create a cache with 5-minute TTL
let mut cache = new;
// Insert data
cache.insert;
// Retrieve data
match cache.get
// Check if expired
if let Ok = cache.get
Custom Matching
The library provides powerful pattern matching capabilities:
use *;
use Duration;
let mut cache = new;
// Insert data
cache.insert;
cache.insert;
cache.insert;
// Find by prefix
let user_matcher = new;
let users = cache.get_all_by_matcher;
println!;
// Find first match
if let Ok = cache.get_by_matcher
Built-in Matchers
PrefixMatcher- Match strings by prefixSuffixMatcher- Match strings by suffixContainsMatcher- Match strings containing substringRangeMatcher<T>- Match numeric values in rangeFnMatcher<T, F>- Custom function-based matchingExactMatcher<T>- Exact matching (useful in generic code)
Custom Matchers
Implement the Matcher<T> trait for domain-specific matching:
// Usage
let company_matcher = DomainMatcher ;
let company_emails = cache.get_all_by_matcher;
Size-Limited Caches
use *;
use Duration;
// Cache with max 1000 entries, oldest removed first
let mut cache = with_max_size;
// Fill beyond capacity - oldest entries automatically removed
for i in 0..1500
assert_eq!; // Only newest 1000 entries remain
Per-Entry TTL
use *;
use Duration;
let mut cache = new; // Default TTL
// Insert with custom TTL
cache.insert_with_ttl;
Error Handling
use *;
match cache.get
Cache Management
use *;
let mut cache = new;
// Manual cleanup
let removed = cache.cleanup_expired;
println!;
// Cache statistics
let stats = cache.stats;
println!;
// Iterate over active entries only
for in cache.iter_active
// Clear all entries
cache.clear;
Performance Characteristics
- Insert: O(1) average case
- Exact lookup: O(1) average case
- Pattern matching: O(n) where n is cache size
- Cleanup: O(k) where k is number of expired entries
- Memory: Minimal overhead, only stores necessary metadata
Examples
The library includes several examples demonstrating different use cases:
basic_usage.rs- Basic cache operations and expirationregex_matching.rs- Advanced pattern matching with regex (requiresregex_supportfeature)file_cache.rs- File content caching with directory matching
Run examples with:
# Basic usage
# Regex matching (requires regex_support feature)
# File caching
Optional Features
Regex Support
Enable regex-based matching by adding the regex_support feature:
[]
= { = "0.1.0", = ["regex_support"] }
This provides RegexMatcher for complex pattern matching.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Changelog
0.1.0
- Initial release
- Basic caching with TTL support
- Custom matcher system
- Size-limited caches with FIFO eviction
- Comprehensive test coverage
0.1.1
- Added traits
Debug&CloneforSimpleCacher&SimpleCacheObject