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 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
/*! [![](https://docs.rs/rent_to_own/badge.svg)](https://docs.rs/rent_to_own/) [![](https://img.shields.io/crates/v/rent_to_own.svg)](https://crates.io/crates/rent_to_own) [![](https://img.shields.io/crates/d/rent_to_own.png)](https://crates.io/crates/rent_to_own) [![Build Status](https://travis-ci.org/fitzgen/rent_to_own.png?branch=master)](https://travis-ci.org/fitzgen/rent_to_own) `RentToOwn<T>`: A wrapper type for optionally giving up ownership of the underlying value. `RentToOwn<T>` is useful in situations where 1. a function might want to *conditionally take ownership* of some `T` value, and 2. that function cannot take the `T` by value and return an `Option<T>` to maybe give the `T` value back if it doesn't want ownership. `RentToOwn<T>` dereferences (immutably and mutably) to its inner `T` value, and additionally provides a `take` method that gives up ownership of the inner value to the caller. Under the covers, `RentToOwn<T>` is essentially an `Option<T>` that gets unwrapped when dereferenced and calls `Option::take` if we need to take ownership of the inner value. The key advantage over using `Option<T>` directly, other than the `Deref` sugar, is some lifetime trickery to statically prevent all unwrapping panics that would arise from using the `RentToOwn<T>` wrapper again after the inner value has been taken. Once the inner value is taken, the borrow checker will ensure that the original `RentToOwn<T>` cannot be used anymore. See the `take` method's documentation for details. ## Example In this example, if the `configure` function encounters any errors, we do not wish to drop the `BigExpensiveResource`, but instead allow the caller to handle the error and then reuse the resource. In effect, the `configure` function is conditionally taking ownership of the `BigExpensiveResource` depending on if there are IO errors or not. ``` use rent_to_own::RentToOwn; use std::io::{self, Read}; use std::fs; /// This is a big, expensive to create (or maybe even unique) resource, and we /// want to reuse it even if `configure` returns an error. struct BigExpensiveResource { // ... } #[derive(Default)] struct Config { // ... } /// A big, expensive resource that has been properly configured. struct ConfiguredResource { resource: BigExpensiveResource, config: Config, } fn read_and_parse_config_file() -> io::Result<Config> { // ... # Ok(Config {}) } fn configure<'a>( resource: &'a mut RentToOwn<'a, BigExpensiveResource> ) -> io::Result<ConfiguredResource> { // We use normal error propagation with `?`. Because we haven't `take`n the // resource out of the `RentToOwn`, if we early return here the caller still // controls the `BigExpensiveResource` and it isn't dropped. let config = read_and_parse_config_file()?; // Now we `take` ownership of the resource and return the configured // resource. let resource = resource.take(); Ok(ConfiguredResource { resource, config }) } ``` What does `configure`'s caller look like? It calls `RentToOwn::with` to construct the `RentToOwn<BigExpensiveResource>` and invoke a closure with it. Then it inspects the results of the closure and whether the `BigExpensiveResource` was taken or not. In this example, the caller can recover from any IO error when reading or parsing the configuration file and use a default configuration with the `BigExpensiveResource` instead. ``` # use rent_to_own::RentToOwn; # struct BigExpensiveResource; # impl BigExpensiveResource { fn reconstruct() -> Self { BigExpensiveResource } } # #[derive(Default)] # struct Config; # struct ConfiguredResource { # resource: BigExpensiveResource, # config: Config, # } # fn configure<'a>( # resource: &'a mut RentToOwn<'a, BigExpensiveResource> # ) -> ::std::io::Result<ConfiguredResource> { # unimplemented!() # } fn use_custom_configuration_or_default(resource: BigExpensiveResource) -> ConfiguredResource { // We pass the resource into `with` and it constructs the `RentToOwn` // wrapper around it and then gives the wrapper to the closure. Finally, it // returns a pair of an `Option<BigExpensiveResource>` which is `Some` if // the closure took ownership and `None` if it did not, and the closure's // return value. let (resource, result) = RentToOwn::with(resource, |resource| { configure(resource) }); if let Ok(configured) = result { return configured; } // Reuse the resource if the closure did not take ownership or else // reconstruct it if the closure did take ownership. (In this particular // example, we know that `configure` took ownership if and only if the // result was `Ok`, but that doesn't hold for all possible examples.) // Finally, return the configured resource with the default configuration. let resource = resource.unwrap_or_else(|| BigExpensiveResource::reconstruct()); let config = Config::default(); ConfiguredResource { resource, config } } ``` */ #![deny(missing_docs)] #![deny(missing_debug_implementations)] use std::ops::{Deref, DerefMut}; /// A wrapper around a `T` that allows users to conditionally take ownership of /// the inner `T` value, or simply use it like a `&mut T` reference. /// /// See the module documentation for details and examples. #[derive(Debug, Hash)] pub struct RentToOwn<'a, T: 'a> { inner: &'a mut Option<T>, } impl<'a, T> Deref for RentToOwn<'a, T> { type Target = T; fn deref(&self) -> &T { self.inner.as_ref().unwrap() } } impl<'a, T> DerefMut for RentToOwn<'a, T> { fn deref_mut(&mut self) -> &mut T { self.inner.as_mut().unwrap() } } impl<'a, T: 'a> RentToOwn<'a, T> { /// Give the function `f` the option to take ownership of `inner`. /// /// That is, create a `RentToOwn` from the given `inner` value and then /// invoke the function `f` with it. /// /// The return value is a pair of: /// /// 1. If the closure took ownership of the inner value, `None`, otherwise /// `Some(inner)`. /// /// 2. The value returned by the closure. /// /// See the module level documentation for details and examples. pub fn with<F, U>(inner: T, f: F) -> (Option<T>, U) where F: for<'b> FnOnce(&'b mut RentToOwn<'b, T>) -> U, { let mut inner = Some(inner); let u = { let mut me = RentToOwn { inner: &mut inner }; f(&mut me) }; (inner, u) } } impl<'a, T> RentToOwn<'a, T> { /// Take ownership of the inner `T` value. /// /// Note that the lifetime on the `self` reference forces the mutable borrow /// to last for the rest of the `RentToOwn`'s existence. This "tricks" the /// borrow checker into statically disallowing use-after-take, which would /// otherwise result in a panic if you were using `Option<T>` instead of /// `RentToOwn<T>`. /// /// ```compile_fail /// use rent_to_own::RentToOwn; /// /// struct Thing(usize); /// /// fn use_after_take<'a>(outer: &'a mut RentToOwn<'a, Thing>) { /// // Take ownership of the inner value, moving it out of the /// // `RentToOwn`. /// let inner = outer.take(); /// /// let inner_val = inner.0; /// println!("inner's value is {}", inner_val); /// /// // An attempt to use the `RentToOwn` again (via deref) after its /// // value has already been taken! /// let outer_val = outer.0; /// println!("outer's value is {}", outer_val); /// } /// ``` /// /// Attempting to compile that example results in a compilation error: /// /// ```text /// error[E0502]: cannot borrow `*outer` as immutable because it is also borrowed as mutable /// --> src/lib.rs:18:21 /// | /// 11 | let inner = outer.take(); /// | ----- mutable borrow occurs here /// ... /// 18 | let outer_val = outer.0; /// | ^^^^^ immutable borrow occurs here /// 19 | println!("outer's value is {}", outer_val); /// 20 | } /// | - mutable borrow ends here /// ``` pub fn take(&'a mut self) -> T { self.inner.take().unwrap() } } #[cfg(test)] mod tests { use super::RentToOwn; #[test] fn it_derefs() { RentToOwn::with(5, |x| { assert_eq!(**x, 5); }); } #[test] fn it_derefs_mut() { RentToOwn::with(5, |x| { **x = 6; assert_eq!(**x, 6); }); } #[test] fn it_takes() { RentToOwn::with(5, |x| { assert_eq!(x.take(), 5); }); } #[test] fn with_returns_closures_result() { let (_, x) = RentToOwn::with(5, |_| 9); assert_eq!(x, 9); } #[test] fn with_gives_back_untaken_ownership() { let (orig, _) = RentToOwn::with(5, |_| {}); assert_eq!(orig, Some(5)); } #[test] fn with_does_not_give_back_taken_ownership() { let (orig, _) = RentToOwn::with(5, |x| x.take()); assert!(orig.is_none()); } }