periodic/lib.rs
1//! # Periodic: datastructures over a lattice
2//!
3//! The dual space of a lattice is _periodic_, meaning that it is bounded and, reaching
4//! those boundaries, one returns to the starting point. A tipical (non-trivial) example
5//! of a periodic space is a sphere: choose a direction and go straight: you will always
6//! return to the starting point.
7//!
8//! This analogy aims to describe how this crate is conceived and what purpose it
9//! serves: it offers two modules, [`ring`][r], that expose implementation of periodic
10//! Vec-like structs, and [`map`][m], that offers a HashMap-like struct that overwrites
11//! its key-value pairs after a certain capacity has been reached.
12//!
13//! ## Why?
14//!
15//! What are these structures for? Their main use is to have caches that occupy a
16//! constant amount of _slots_ of memory, being therefore limited in the amount of
17//! consumed memory, but a cache of a very simplistic nature:
18//! _first-in-first-overwritten-when-full_.
19//!
20//! ## How?
21//!
22//! The simplest api of this package is the following:
23//!
24//! ```rust
25//! use periodic::map::RingDict;
26//!
27//! // 3 is the total capacity
28//! let mut rd: RingDict<&str, i32> = RingDict::new(3);
29//! rd.insert("a", 1);
30//! rd.insert("b", 2);
31//! rd.insert("c", 3);
32//! assert_eq!(rd.get("a"), Some(&1));
33//! assert_eq!(rd.get("b"), Some(&2));
34//! assert_eq!(rd.get("c"), Some(&3));
35//!
36//! // Now we add a new key-value pair, overcoming the capacity
37//! rd.insert("d", 4);
38//! assert_eq!(rd.get("d"), Some(&4));
39//! assert!(rd.get("a").is_none());
40//! ```
41//! [r]: `crate::ring`
42//! [m]: `crate::map`
43
44pub mod map;
45pub mod ring;