Transform owned strings in place

Modifying an owned String behind a mutable reference often requires creating a temporary value or using std::mem::replace if you have a replacement ready. The take_mut::take function allows you to temporarily move the value out of the mutable reference, transform it as an owned object, and then place it back.

The following example demonstrates how to append text to an owned String by taking it from a mutable reference and returning the modified instance.

fn main() {
    use take_mut::take;

    let mut message = String::from("Hello");

    // Take ownership of the String from the mutable reference
    take(&mut message, |mut s| {
        s.push_str(" world");
        s // Return the owned String to put it back
    });

    assert_eq!(message, "Hello world");
}

You can also perform more complex transformations that consume the original String and return a completely different one. This is useful for operations like case conversion or filtering that might reallocate or change the underlying data structure.

fn main() {
    use take_mut::take;

    let mut data = String::from("rust_programming");

    // Transform the string by creating a new uppercase version
    take(&mut data, |s| {
        s.to_uppercase()
    });

    assert_eq!(data, "RUST_PROGRAMMING");
    assert_eq!(data.len(), 16);
}

When using take_mut::take, the closure must return a valid value of the same type. If the closure panics, take_mut cannot safely restore the value to the mutable reference, and the program will exit immediately to prevent undefined behavior.