write with inplace mutation only

[purpleKarrot]

For many mutable operations, there is a transform operation that can be
applied to perform the copy with the mutation in a more efficient manner. (source)

Is that so? It would be good to cover that in the example. For the more common case, where the transform is implemented in terms of the inplace mutation, it would be good to have an overload with just one argument. It would also make sense to swap the positions of the two arguments:

    template <class Inplace, class Transform>
    auto write(Inplace inplace, Transform transform) -> element_type&;

    template <class Inplace>
    auto write(Inplace inplace) -> element_type& {
        return write(inplace, [&](const element_type& x) {
            element_type tmp = x;
            inplace(tmp);
            return tmp;
        });
    }

It is error prone to provide both inplace and transform. Inconsistencies may sneak in, as the example proves:

https://github.com/stlab/copy-on-write/blob/64a1e44805b872c6a5db953e39f34295d580232e/example/basic_usage.cpp#L66-L77

When you want to remove the last element of the document (index == size()), you will observe different behaviour depending on the usage count.

[purpleKarrot]

You may disagree with my statement above that the inplace mutation is more common. Here is an alternative approach that provides two single-argument overloads: One for transformation and one for action: purpleKarrot@48e5866

[sean-parent]

The current strategy supports writing with inplace mutation only.

auto& lines{_lines.write()};
lines.erase(line.begin() + index);

The two-argument write allows an alternative transformation instead of just a copy.

I would be willing to accept a PR that allowed:

_lines.write([](auto& lines) { lines.erase(lines.begin() + index); })

and even deprecate the older write() (which predates lambdas). But it doesn't remove the need for the two-argument case.

The inconsistency in the old example was because I let AI write it at the end of the day and forgot to review it the next day.