#mutability #replace #chat #content #pattern

no-std replace_with

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

1 unstable release

new 0.1.8 May 20, 2025
0.1.7 Aug 14, 2020
0.1.6 Jul 18, 2020
0.1.5 Oct 17, 2019
0.1.2 Nov 27, 2018

#66 in Rust patterns

Download history 48484/week @ 2025-02-01 125444/week @ 2025-02-08 134733/week @ 2025-02-15 169259/week @ 2025-02-22 189388/week @ 2025-03-01 162686/week @ 2025-03-08 173769/week @ 2025-03-15 147371/week @ 2025-03-22 143594/week @ 2025-03-29 136943/week @ 2025-04-05 117036/week @ 2025-04-12 112995/week @ 2025-04-19 115482/week @ 2025-04-26 120395/week @ 2025-05-03 116593/week @ 2025-05-10 94316/week @ 2025-05-17

465,584 downloads per month
Used in 274 crates (51 directly)

MIT/Apache

28KB
245 lines

replace_with

Crates.io MIT / Apache 2.0 licensed Build Status

📖 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 function replace_with(), which is like std::mem::replace() except it allows the replacement value to be mapped from the original value.

See RFC 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 to take_mut, though uses Drop instead of std::panic::catch_unwind() to react to unwinding, which avoids the optimisation barrier of calling the extern "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 (as take_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 with replace_with_or_abort().

Example

Consider this motivating example:

enum States {
    A(String),
    B(String),
}

impl States {
    fn poll(&mut self) {
        // error[E0507]: cannot move out of borrowed content
        *self = match *self {
            //        ^^^^^ cannot move out of borrowed content
            States::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:

enum States {
    A(String),
    B(String),
}

impl States {
    fn poll(&mut self) {
        replace_with_or_abort(self, |self_| match self_ {
            States::A(a) => States::B(a),
            States::B(a) => States::A(a),
        });
    }
}

Huzzah!

no_std

To use replace_with with no_std you have to disable the std feature, which is active by default, by specifying your dependency to it like this:

# Cargo.toml

replace_with = { version = "0.1", default-features = false }

The nightly feature can be enabled to use core::intrinsics::abort() instead of triggering an abort via std::process::abort() or extern "C" fn abort() { panic!() } abort().

License

Licensed under either of

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.

No runtime deps

Features