Library to safely and fallibly initialize pinned structs in-place.

It also allows in-place initialization of big structs that would otherwise produce a stack overflow.

The problem

When writing self referential data structures in Rust, one runs into the issue of initializing them. For example we will create an intrusive, doubly linked, circular list in Rust:

```rust use core::{ptr::NonNull, marker::PhantomPinned}; use pinned_init::*;

pin_data! { pub struct ListHead { next: NonNull, prev: NonNull, // ListHead is !Unpin because next.prev = self #pin _pin: PhantomPinned, } } ```

But now, how would one go about creating a ListHead? A valid initial state of a singular ListHead is, with next and prev pointing to self. But in Rust we cannot get a hold of self until we have selected a value for next!

This library

This library provides the means to achieve this safely: ```rust use core::{ptr::NonNull, marker::PhantomPinned}; use pinned_init::*;

pin_data! { pub struct ListHead { next: NonNull, prev: NonNull, // ListHead is !Unpin because next.prev = self #pin _pin: PhantomPinned, } }

impl ListHead { pub fn newinplace() -> impl PinInit { pininit!(&this in ListHead { next: this, prev: this, _pin: PhantomPinned, }) } } `` Insead of writingnew() -> Selfwe writenewinplace() -> impl PinInit. This function now returns an in-place initializer. Thepininit!` macro used to create this initializer has the same syntax as a struct initializer. You will need to specify every field and can use arbitrary expressions. When an expression evaluates to an in-place initializer from this library, it is used to initialize the value in-place.