Mutable.replace_with() confusion

[sullyj3]

Hi! Thanks for this library, I'm really enjoying it!

One thing I'm confused about is what the rationale is for having the function passed to replace_with take a mutable reference. Why not FnOnce(&A) -> A?

pub fn replace_with<F>(&self, f: F) -> A where F: FnOnce(&mut A) -> A {
    let mut state = self.state().lock.write().unwrap();

    let new_value = f(&mut state.value);
    let value = std::mem::replace(&mut state.value, new_value);

    state.notify(true);

    value
}

If I'm understanding this correctly, the function f can choose to mutate the internal state of the Mutable through the mutable reference &mut state.value. My assumption is that the ordinary way to use replace_with is just to have f return the new value to be placed inside the Mutable without directly mutating through that reference. This is the interface that makes intuitive sense to me.

What's really confusing to me is that if f does choose to mutate through the reference, the referent of that reference is immediately overwritten with the return value of f by the mem::replace call. So then what was the point of mutating it? The only other thing that would happen in the case of mutation would be that the caller of replace_with is given back value, which I guess would be whatever value f wrote through &mut state.value.

But I don't understand why it would be useful to the caller to receive back the result of the mutation that f, the function they just provided, performed. Whereas in the case where f doesn't mutate and just returns a new value, it makes sense to me that it would be useful to the caller to learn the previous value of the Mutable.

[Pauan]

My assumption is that the ordinary way to use replace_with is just to have f return the new value to be placed inside the Mutable without directly mutating through that reference. This is the interface that makes intuitive sense to me.

Your assumption is correct. Because the closure must return an owned value, it cannot (directly) return the reference, so it will usually return a completely new value.

The only other thing that would happen in the case of mutation would be that the caller of replace_with is given back value, which I guess would be whatever value f wrote through &mut state.value.

Yes, that is one possible use case.

But the bigger use case is when the closure needs to mutate the value in order to return a new value.

The best example I have is using Option::take:

mutable.replace_with(|value| {
    do_something_with_owned_value(value.take())
})

By using Option::take you can take ownership of the old value and then do something with it that requires ownership.

But Option::take requires a &mut self reference.

This is admittedly a rare and niche use case... but I designed the APIs to be as flexible as possible.

Also, the Mutable APIs try to copy from existing APIs as much as possible. The RefCell::replace_with also gives a &mut reference.

---

Note that replace_with is an older API, it has been superseded by lock_mut():

let value = mutable.lock_mut();
*value = do_something_with(&value);

That is equivalent to this:

mutable.replace_with(|value| {
    do_something_with(value)
});

The advantage of using lock_mut() is that it gives you a lot more flexibility, and if you don't mutate the lock then it won't notify the downstream subscribers. This allows you to do conditional mutation:

let value = mutable.lock_mut();

if some_condition(&value) {
    *value = do_something_with(&value);
}

It's also generally clearer and easier to understand for people who are reading your code.

[sullyj3]

Thanks, that makes sense. I think my confusion arose from the fact that I'm using a Mutable<u8> for my use case, and reasoning using that intuition without considering cases where you're storing more complex data.

I hadn't realised lock_mut was supposed to supersede replace_with, but that makes sense, I can see the argument that it's clearer. I saw lock_mut in the tutorial, but I gravitated towards replace_with when I saw it in the docs because I'm used to writing FP.

I was actually hoping for an API that doesn't take a reference at all, so that if I have a function like

fn add_one(x: u8) -> u8 {
  x + 1
}

, then instead of

let my_mutable = Mutable::new(0);
my_mutable.replace_with(|v| add_one(*v));

or

let value = my_mutable.lock_mut();
*value = add_one(*value);

, I could write

my_mutable.replace_pure(add_one);

Is an addition like that something you'd consider?

Users can obviously get this as a function trivially:

fn replace_pure<T, F>(mutable: &Mutable<T>, f: F)
where
    T: Copy,
    F: FnOnce(T) -> T,
{
    let mut value = mutable.lock_mut();
    *value = f(*value);
}

replace_pure(my_mutable, add_one);

but it'd be nice to have it as a method.

Edit: just realised I can also do:

trait MutableExt<T> {
    fn replace_pure<F>(&self, f: F)
    where
        T: Copy,
        F: FnOnce(T) -> T;
        
  
    fn replace_pure_clone<F>(&self, f: F)
    where
        T: Clone,
        F: FnOnce(T) -> T;
}

impl<T> MutableExt<T> for Mutable<T> {
    fn replace_pure<F>(&self, f: F)
    where
        T: Copy,
        F: FnOnce(T) -> T,
    {
        let mut value = self.lock_mut();
        *value = f(*value);
    }
    
    fn replace_pure_clone<F>(&self, f: F)
    where
        T: Clone,
        F: FnOnce(T) -> T,
    {
        let mut value = self.lock_mut();
        *value = f(value.clone());
    }
}

[Pauan]

That would require _copy and _clone variations of all the methods, which adds a lot of complexity for minimal benefit.

The problem is that in Rust there are many different ways to convert from a reference to an owned value. For example, to_string, to_owned, clone, to_vec, etc.

So it makes sense to just give a reference and let the user decide how to convert the reference into an owned value.

---

For simple Copy values you can use argument destructuring which is a bit cleaner:

my_mutable.replace_with(|&v| add_one(v));

Also, for simple values like numbers you can often do things like this:

*mutable.lock_mut() += 1;

This is because the operators (like Add) accept a reference, even for Copy types like numbers.

---

You can achieve the same effect within your own code by using the Borrow trait:

fn add_one(value: impl Borrow<u8>) -> u8 {
    *value.borrow() + 1
}

Now your add_one function will work with owned values and references:

add_one(5);
add_one(&5);
my_mutable.replace_with(add_one);

[sullyj3]

So it makes sense to just give a reference and let the user decide how to convert the reference into an owned value.

That does make sense.

The other tips are helpful, thanks!