Expand description
This crate provides convenient wrappers for dealing with &mut Option<T>
. There are two main types, OptionGuard
and OptionGuardMut
:
§OptionGuard
Using EmptyOptionExt::steal
on an &mut Option<T>
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:
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<T>`.
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.
use empty_option::EmptyOptionExt;
let mut thing = Some(5);
let (_, _) = thing.steal();
// Never return the value!
Calling .steal()
on a None
immediately panics:
let mut thing = None;
// Panics here!
let (guard, _) = thing.steal();
guard.restore(5);
§OptionGuardMut
Using EmptyOptionExt::steal_mut
on an &mut Option<T>
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:
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.
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:
let mut thing: Option<i32> = None;
// Panics here!
thing.steal_mut();
Structs§
- Option
Guard - An option which has had its value taken. On
Drop
,OptionGuard
will panic - in order to prevent a panic, the stolen value must be moved back in withOptionGuard::restore
. - Option
Guard Mut - A value taken from an
Option<T>
.OptionGuardMut<T>
dereferences to aT
, and the innerT
can be moved out withOptionGuardMut::into_inner
. When dropped, theOptionGuardMut
moves the taken value back into theOption
it came from.
Traits§
- Empty
Option Ext - Extension trait providing nice method sugar for
steal
andsteal_mut
.