# Incremental Structure

[![crates.io](https://img.shields.io/crates/v/incrstruct)](https://crates.io/crates/incrstruct)
[![docs.rs](https://img.shields.io/badge/incrstruct-66c2a5?style=flat&logo=docsdotrs&label=docs.rs)](https://docs.rs/incrstruct)
[![GitHub last commit](https://img.shields.io/github/last-commit/tommie/incrstruct)](https://github.com/tommie/incrstruct)

A [Rust](https://rust-lang.org/) crate for building self-referencing structs using two-phase initialization.

## Example

```rust
use std::cell::{Ref, RefCell};
use incrstruct::IncrStruct;

#[derive(IncrStruct)]
struct AStruct<'a> {
    #[borrows(b)]             // Borrowing from a tail field
    c: &'a Ref<'a, i32>,      // is possible.

    #[borrows(a)]             // You can only borrow from fields that
    b: Ref<'a, i32>,          // come after the current field.

    a: RefCell<i32>,          // A head field. Since you can only borrow
                              // immutable references, RefCell is useful.

    #[header]                 // The required header field.
    hdr: incrstruct::Header,  // The name is arbitrary.
}

// The AStructInit trait is generated by the derive macro and
// ensures the contract between the incrstruct library code and
// the user provided code matches. The functions are invoked in
// reverse field declaration order.
impl<'a> AStructInit<'a> for AStruct<'a> {
    fn init_field_c(b: &'a Ref<'a, i32>) -> &'a Ref<'a, i32> {
        b
    }

    fn init_field_b(a: &'a RefCell<i32>) -> Ref<'a, i32> {
        a.borrow()
    }
}

// Only head fields are provided to the generated `new_X` functions.
let my_a = AStruct::new_box(RefCell::new(42));

assert_eq!(*my_a.a.borrow(), *my_a.b);
```

See the [documentation](https://docs.rs/incrstruct) for more information.