Repository files navigation

📖 Docs |💬 Chat

Temporarily take ownership of a value at a mutable location, and replace it with a new value based on the old one.

This crate provides the functionreplace_with(), which is likestd::mem::replace() except it allows the replacement value to be mapped from the original value.

SeeRFC 1736 for a lot of discussion as to its merits. It was never merged, and the desired ability to temporarily move out of&mut T doesn't exist yet, so this crate is my interim solution.

It's very akin totake_mut, though usesDrop instead ofstd::panic::catch_unwind() to react to unwinding, which avoids the optimisation barrier of calling theextern "C" __rust_maybe_catch_panic(). As such it's up to ∞x faster. The API also attempts to make slightly more explicit the behavior on panic –replace_with() accepts two closures such that aborting in the "standard case" where the mapping closure (FnOnce(T) -> T) panics (astake_mut::take() does) is avoided. If the second closure (FnOnce() -> T) panics, however, then it does indeed abort. The "abort on first panic" behaviour is available withreplace_with_or_abort().

Consider this motivating example:

enumStates{A(String),B(String),}implStates{fnpoll(&mutself){// error[E0507]: cannot move out of borrowed content*self =match*self{//        ^^^^^ cannot move out of borrowed contentStates::A(a) =>States::B(a),States::B(a) =>States::A(a),};}}

Depending on context this can be quite tricky to work around. With this crate, however:

enumStates{A(String),B(String),}implStates{fnpoll(&mutself){replace_with_or_abort(self, |self_|match self_{States::A(a) =>States::B(a),States::B(a) =>States::A(a),});}}

Huzzah!

To usereplace_with withno_std you have to disable thestd feature, which is active by default, by specifying your dependency to it like this:

# Cargo.tomlreplace_with = {version ="0.1",default-features =false }

Thenightly feature can be enabled to usecore::intrinsics::abort() instead of triggering an abort viastd::process::abort() orextern "C" fn abort() { panic!() } abort().

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE.txt orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT.txt orhttp://opensource.org/licenses/MIT)

at your option.

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.