# Takeable

> A simple wrapper type that holds values that need to be moved out from only a mutable reference.

## [Documentation](https://docs.rs/takeable/latest/takeable/)

Sometimes it's useful to be able to move out of a mutable reference
temporarily or permanently. This often occurs for instance when dealing with state machines
implemented using an enum. For instance let's say you have the following state
machine:

```rust
enum State {
    Starting,
    Running(Resource1, Resource2),
    Finished(Option<Resource2>)
}
```

Let's say that you want to implement a function that changes state from
`Running` to `Finished`. The naive approach would be:

```rust
pub fn to_finished(state: &mut State) {
    let newstate = match *state {
        State::Starting => State::Finished(None),
        State::Running(_, r) => State::Finished(Some(r)),
        State::Finished(r) => State::Finished(r),
    };
    *state = newstate;
}
```

However, this would fail with a "cannot move out of borrowed content" error.

There are a few solutions to this problem:

- Use an `Option<State>`. Temporarily set it to `None` to move out the
  state.

- Introduce a new, invalid state for the same purpose.

- Use [`take`][take] from the [`take_mut`][take_mut] crate.

- Restructure your code to avoid the problem.

[take]: https://docs.rs/take_mut/latest/take_mut/fn.take.html
[take_mut]: https://crates.io/crates/take_mut

Depending on your scenario, any of these options might be preferable. This crate
provides a wrapper around an `Option<T>` with an API that forces correct usage
of the `Option`. This approach also has the advantage that it allows the
performance-optimization of not actually checking the enum-tag outside of
destructor-logic.

Using this library, the code could have been written like this:

```rust
struct StateMachine(Takeable<State>);

enum State {
    Starting,
    Running(Resource1, Resource2),
    Finished(Option<Resource2>)
}

pub fn to_finished(state: &mut StateMachine) {
    state.0.borrow(|state| {
        match state {
            State::Starting => State::Finished(None),
            State::Running(_, r) => State::Finished(Some(r)),
            State::Finished(r) => State::Finished(r),
        }
    });
}
```

It can also sometimes be useful to permanently move a value out while only
having a mutable reference. One such use case is when implementing `drop` and
needing to call a method of a field that consumes the field. This can be done
using this crate as follows:

```rust
struct Resource;
impl Resource {
    pub fn close(self) {}
}

struct ResourceUser {
    resource: Takeable<Resource>;
}
impl Drop for ResourceUser {
    fn drop(&mut self) {
        self.resource.take().close();
    }
}
```

The above code would also work by using an `Option` directly instead of a
`Takeable`. However, the latter has the advantage that it is clear by its
type that it must always have a value, and also that `None` variants do not
have to be handled when accessing the `Resource` elsewhere. Rather, the
`Takeable` will panic if this is attempted after the value has been moved
out.