# Heapnotize

A Rust library providing memory allocation on the stack.

Heapnotize can be used to store values somewhere in memory while keeping a
reference to them. Like [`Box`](https://doc.rust-lang.org/std/boxed/index.html),
it can be used for nested types for which indirection is required. Unlike `Box`,
this library is implemented with `#[no_std]` and thus it can help with memory
management on microcontrollers.

The two main data types of Heapnotize are `Rack` and `Unit`. `Rack` is used to
allocate predefined chunk of the stack for a predefined type. `Unit` provides an
ownership for values stored there. `Unit` also ensures that once it goes out of
scope, the value it refers to will be properly dropped.

Documentation:

* [API reference (docs.rs)](https://docs.rs/heapnotize)
* [Repository (github.com)](https://github.com/zlosynth/heapnotize)
* [Crate (crates.io)](https://crates.io/crates/heapnotize)

## Usage

Add the following to your `Cargo.toml`:

``` toml
[dependencies]
heapnotize = "1.1"
```

In order to store values on the stack, we first need to initialize the `Rack`
with a specific capacity. Available capacities are currently powers of 2 from 1
up to 1024. The whole size will be allocated when a `Rack` is created. After
that, it is possible to store values on the rack and get a handle on them as
`Unit` object. It is the possible to derefence the `Unit` to get access to the
value. Once the `Unit` gets out of scope, the value would be freed from the
rack:

``` rust
fn main() {
    let rack = Rack64::new();
    let unit = rack.must_add(10);
    assert_eq!(*unit, 10);
}
```

Where Heapnotize may become really handy is when dealing with recursive types,
where a type contains a value of the same time. Rust cannot know how much memory
a recursive type requires on compile time, therefore, indirection must be used.
This is nicely covered in [The
Book](https://doc.rust-lang.org/book/ch15-01-box.html#enabling-recursive-types-with-boxes)
where `Box` is used to enable this, that however requires use of the heap.
The following example shows how to handle recursive types on the stack using
`Rack` and `Unit`:

``` rust
enum List<'a> {
    Cons(i32, Unit<'a, List<'a>>),
    Nil,
}

use List::{Cons, Nil};

fn main() {
    let rack = Rack64::new();
    let list = Cons(1, rack.must_add(Cons(2, rack.must_add(Cons(3, rack.must_add(Nil))))));
}
```

See the [documentation](https://docs.rs/heapnotize) to learn more.

# License

Heapnotize is distributed under the terms of the General Public License
version 3. See [LICENSE](LICENSE) for details.

# Changelog

Read the [CHANGELOG.md](CHANGELOG.md) to learn about changes introduced in each
release.