# Periodic: datastructures over a lattice

![periodic logo](./assets/logo.png)

The dual space of a lattice is _periodic_, meaning that it is bounded and, reaching
those boundaries, one returns to the starting point. A tipical (non-trivial) example
of a periodic space is a sphere: choose a direction and go straight: you will always
return to the starting point.

This analogy aims to describe how this crate is conceived and what purpose it
serves: it offers two modules, `ring`, that expose implementation of periodic
Vec-like structs, and `map`, that offers a HashMap-like struct that overwrites its
key-value pairs after a certain capacity has been reached.

## What?

If you want to use this library in your project, you can add this to your cargo
dependencies:

```
periodic-rs = "0.2.1"
```

## Why?

What are these structures for? Their main use is to have caches that occupy a
constant amount of _slots_ of memory, being therefore limited in the amount of
consumed memory, but a cache of a very simplistic nature:
_first-in-first-overwritten-when-full_.

> Of course, the real underlying reason for the author to create this work was to
> learn some rust.

## How?

The simplest api of this package is the following:

```rust
use periodic::map::RingDict;

// 3 is the total capacity
let mut rd: RingDict<&str, i32> = RingDict::new(3);
rd.insert("a", 1);
rd.insert("b", 2);
rd.insert("c", 3);
assert_eq!(rd.get("a"), Some(&1));
assert_eq!(rd.get("b"), Some(&2));
assert_eq!(rd.get("c"), Some(&3));

// Now we add a new key-value pair, overcoming the capacity
rd.insert("d", 4);
assert_eq!(rd.get("d"), Some(&4));
assert!(rd.get("a").is_none());
```

## Contacts

You can email the author at:

> blallo -|AT|- autistici -dot- org