https://github.com/sdleffler/empty-option-rs
A small library for dealing with mutable references to the option type in Rust.
https://github.com/sdleffler/empty-option-rs
option-type patterns rust
Last synced: 10 days ago
JSON representation
A small library for dealing with mutable references to the option type in Rust.
- Host: GitHub
- URL: https://github.com/sdleffler/empty-option-rs
- Owner: sdleffler
- License: apache-2.0
- Created: 2017-06-16T18:59:31.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-06-16T19:31:47.000Z (about 9 years ago)
- Last Synced: 2025-10-26T19:51:43.105Z (9 months ago)
- Topics: option-type, patterns, rust
- Language: Rust
- Size: 12.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
[](https://travis-ci.org/sdleffler/empty-option-rs)
[](https://docs.rs/empty-option)
[](https://crates.io/crates/empty-option)
# empty-option: guards for safely taking and dealing with values from mutable references to `Option`
This crate provides convenient wrappers for dealing with `&mut Option`. There are two main types, `OptionGuard` and `OptionGuardMut`:
## `OptionGuard`
Using `EmptyOptionExt::steal` on an `&mut Option` produces the `T` from the option as well as an `OptionGuard`. If `OptionGuard::restore` is not called before the `OptionGuard` is dropped, then a panic will occur.
### Examples
Calling `guard.restore()` puts the stolen value back into the original option:
```rust
use empty_option::EmptyOptionExt;
// A mutable option, from which we shall steal a value!
let mut thing = Some(5);
// Scope so that when we do `guard.restore()`, the mutable borrow on `thing` will end.
{
// Steal the value - we now have the guard and also a concrete `T` from our `Option`.
let (guard, five) = thing.steal();
assert_eq!(five, 5);
// Move the value back into `thing` - we're done.
guard.restore(6);
}
// The value is returned by `guard.restore()`.
assert_eq!(thing, Some(6));
```
But, if the guard is dropped instead, a runtime panic results.
```rust,should_panic
use empty_option::EmptyOptionExt;
let mut thing = Some(5);
let (_, _) = thing.steal();
// Never return the value!
```
Calling `.steal()` on a `None` immediately panics:
```rust,should_panic
let mut thing = None;
// Panics here!
let (guard, _) = thing.steal();
guard.restore(5);
```
## `OptionGuardMut`
Using `EmptyOptionExt::steal_mut` on an `&mut Option` produces an `OptionGuardMut`, which dereferences to a `T`. To get the inner value out, `OptionGuardMut::into_inner` can be called. On `Drop`, if the `OptionGuardMut` is not consumed with `OptionGuardMut::into_inner`, the value in the `OptionGuardMut` will be returned to the `Option` that it was borrowed from.
### Examples
Take a value from an option, which is automatically returned:
```rust
use empty_option::EmptyOptionExt;
let mut thing = Some(5);
{
let mut stolen = thing.steal_mut();
assert_eq!(*stolen, 5);
*stolen = 6;
}
assert_eq!(thing, Some(6));
```
If the guard is consumed, the value is never returned.
```rust
use empty_option::EmptyOptionExt;
let mut thing = Some(5);
{
// Keep the thing!
let stolen = thing.steal_mut().into_inner();
assert_eq!(stolen, 5);
}
assert_eq!(thing, None);
```
Calling `steal_mut` on a `None` immediately panics:
```rust,should_panic
let mut thing: Option = None;
// Panics here!
thing.steal_mut();
```
## License
Licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.