1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
// Copyright 2017 Mathias Svensson. See the COPYRIGHT file at the top-level
// directory of this distribution.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or https://opensource.org/licenses/MIT> or the Unlicense
// <LICENSE-UNLICENSE or https://unlicense.org/UNLICENSE>, at your option.
// All files in the project carrying such notice may not be copied,
// modified, or distributed except according to those terms.
//! Crate for temporarily or permanently moving out of a mutable pointer.
//!
//! This crate implements a single wrapper-type [`Takeable<T>`]. The main purpose of this wrapper
//! is that it provides two convenient helper functions [`Takeable::borrow`] and [`Takeable::borrow_result`]
//! that allows for temporarily moving out of the wrapper without violating safety. The value can also be permanently
//! moved out, invalidating the container and causing a panic on any future attempts to access
//! the value.
//!
//! The [`Takeable::borrow`] and [`Takeable::borrow_result`] methods work similarly to
//! [`take`] from the [`take_mut`] crate. The main difference is that, while the [`take_mut`]
//! is implemented using careful handling of unwind safety, this crate uses an [`Option<T>`] inside to make
//! unwinding work as expected.
//!
//! The [`Takeable::take`] method works similarly to [`Option::take`], but has the advantage that the object becomes
//! permanently invalidated. Additionally, using a [`Takeable<T>`] instead of an [`Option<T>`] makes
//! it clear in code that a value is always expected and avoids the need to handle possible
//! [`Option::None`] variants when accessing the `T`.
//!
//! [`take`]: https://docs.rs/take_mut/latest/take_mut/fn.take.html
//! [`take_mut`]: https://crates.io/crates/take_mut
#![no_std]
#![deny(
missing_docs,
unsafe_code,
missing_debug_implementations,
missing_copy_implementations,
unstable_features,
unused_import_braces,
unused_qualifications
)]
use core::{
fmt::Display,
ops::{Deref, DerefMut},
};
/// A wrapper-type that always holds a single `T` value.
///
/// This type is implemented using an [`Option<T>`], however, the wrapper requires the [`Option<T>`] to
/// always contain a value.
///
/// # Panics
///
/// If the closure given to [`borrow`][Self::borrow] or [`borrow_result`][Self::borrow_result] panics, then the `Takeable` is left in an
/// invalid state without holding a `T`. Calling any method on the object besides [`is_usable`][Self::is_usable] when
/// in this state will result in a panic. This includes trying to dereference the object. The object
/// will also be permanently invalidated if the value is moved out manually using [`take`][Self::take].
///
/// It is always safe to drop the `Takeable` even when invalidated.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Default)]
pub struct Takeable<T> {
// During normal usage, the invariant is that that this value should *always* be a Some(value),
// unless we are inside the `borrow_result` function. However if the closure given the
// `borrow_result` panics, or the value is taken with `take`, then this will no longer be the
// case.
value: Option<T>,
}
/// Message to print when panicking because the `Takeable<T>` has been invalidated.
const PANIC_MESSAGE: &str = "the value has already been removed from the Takeable";
impl<T> Takeable<T> {
/// Constructs a new [`Takeable<T>`] value.
#[inline(always)]
pub fn new(value: T) -> Takeable<T> {
Takeable { value: Some(value) }
}
/// Takes ownership of the inner value.
#[inline(always)]
#[track_caller]
pub fn into_inner(self) -> T {
self.value.expect(PANIC_MESSAGE)
}
/// Updates the inner value using the provided closure.
#[inline(always)]
#[track_caller]
pub fn borrow<F>(&mut self, f: F)
where
F: FnOnce(T) -> T,
{
self.borrow_result(|v| (f(v), ()))
}
/// Updates the inner value using the provided closure, which also returns a result.
#[inline(always)]
#[track_caller]
pub fn borrow_result<F, R>(&mut self, f: F) -> R
where
F: FnOnce(T) -> (T, R),
{
let old = self.value.take().expect(PANIC_MESSAGE);
let (new, result) = f(old);
self.value = Some(new);
result
}
/// Moves out the inner value and invalidates the object.
///
/// Subsequent calls to any methods except [`is_usable`][Self::is_usable] will panic, including attempts to
/// deference the object.
#[inline(always)]
#[track_caller]
pub fn take(&mut self) -> T {
self.value.take().expect(PANIC_MESSAGE)
}
/// Check if the object is still usable.
///
/// The object will always start out as usable, and can only enter an unusable state if the
/// methods [`borrow`][Self::borrow] or [`borrow_result`][Self::borrow_result] are called with closures that panic, or if the value
/// is explicitly moved out permanently with [`take`][Self::take].
#[inline(always)]
pub fn is_usable(&self) -> bool {
self.value.is_some()
}
}
impl<T: Display> Display for Takeable<T> {
#[inline(always)]
#[track_caller]
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
write!(f, "{}", self.as_ref())
}
}
impl<T> Deref for Takeable<T> {
type Target = T;
#[inline(always)]
#[track_caller]
fn deref(&self) -> &T {
self.as_ref()
}
}
impl<T> DerefMut for Takeable<T> {
#[inline(always)]
#[track_caller]
fn deref_mut(&mut self) -> &mut T {
self.as_mut()
}
}
impl<T> From<T> for Takeable<T> {
#[inline(always)]
#[track_caller]
/// Converts a `T` value into a [`Takeable<T>`].
fn from(value: T) -> Self {
Self::new(value)
}
}
impl<T> AsRef<T> for Takeable<T> {
#[inline(always)]
#[track_caller]
/// Gets a reference to the underlying value.
fn as_ref(&self) -> &T {
self.value.as_ref().expect(PANIC_MESSAGE)
}
}
impl<T> AsMut<T> for Takeable<T> {
#[inline(always)]
#[track_caller]
/// Gets a mutable reference to the underlying value.
fn as_mut(&mut self) -> &mut T {
self.value.as_mut().expect(PANIC_MESSAGE)
}
}
#[cfg(test)]
mod tests {
use super::Takeable;
#[test]
fn test_takeable() {
let mut takeable = Takeable::new(42u32);
*takeable += 1;
assert_eq!(*takeable, 43);
*takeable.as_mut() += 1;
assert_eq!(takeable.as_ref(), &44);
takeable.borrow(|n: u32| n + 1);
assert_eq!(*takeable, 45);
let out = takeable.borrow_result(|n: u32| (n + 1, n));
assert_eq!(out, 45);
assert_eq!(takeable.into_inner(), 46);
let mut takeable = Takeable::new(34u32);
assert_eq!(takeable.take(), 34);
}
#[test]
#[should_panic]
fn test_usable() {
struct MyDrop {
value: Takeable<()>,
should_be_usable: bool,
}
impl Drop for MyDrop {
fn drop(&mut self) {
assert_eq!(self.value.is_usable(), self.should_be_usable);
}
}
let _drop1 = MyDrop {
value: Takeable::new(()),
should_be_usable: true,
};
let mut drop2 = MyDrop {
value: Takeable::new(()),
should_be_usable: false,
};
let mut drop3 = MyDrop {
value: Takeable::new(()),
should_be_usable: false,
};
let _ = drop3.value.take();
drop2.value.borrow(|_| panic!());
}
}