xxxInPlace or xxxCopy?

[Jonathan M Davis]

On Friday, January 21, 2011 10:47:01 so wrote:
> > replace is clearer in the first case, because you're getting the return
> > value.
> > ...
> 
> I am really trying hard to understand this, but your reasons for first is
> clearer then the second makes no sense to me i am sorry.
> I still think second is clearer, but whatever, as long as i can see the
> interface or the doc, i am fine.
> 
> string replace(string, ...);
> void replace(ref string, ...);

The issue is when you don't look at the documentation or trying to avoid having 
to look at the documentation. If you see

auto result = replace(str, "hello", "goodbye");

it's quite clear that a copy is taking place. And if a copy/slice is taking 
place, then that is what you would normally see when replace is used. However, 
if replace alters the array in place, then

replace(str, "hello", "goodbye");

would be what you would normally see. And without looking at the documentation, 
it's not clear whether that is doing it in-place or if you're throwing away the 
return value. However, in the case where replace does a copy/slice, it _is_ 
clear, because the return value is saved.

So, if copying/slicing is the default, then you won't _need_ to read the 
documentation to know whether a copy/slice is happening or whether it's 
happening in-place, because the code itself will make it obvious (unless you 
screwed up and forgot to assign the return value to a variable or pass it to a 
function). But in the case where in-place is the default, it is _not_ obvious by 
reading the code. Sure, once you read the documentation, you'll know. But you 
have to read the documentation. So, copying/slicing by default is immediately 
obvious whereas in-place is not.

> > Regardless, I don't see anything wrong with naming functions in a manner
> > that
> > implies that a functional style is the default
> 
> I am not against enforcing such a rule, i am against doing it implicitly
> and work with assumptions.
> Just check boost/string/replace, they have in place replaces default too.
> You might not like boost (some don't) but it is the closest example to D.

If you want consistency among your function, then you have to pick either 
copying or in place as the default. That doesn't necessarily mean that _all_ 
functions must _always_ be named that way (e.g. the current behavior of sort is 
an interesting example since it does _both_). However, if you're going for 
consistency, then you have to pick one or the other. Unless you want to 
explicitly put Copy and InPlace in all of the array functions and not have any 
without it, you're going to _have_ to deal with the fact that a function without 
Copy or InPlace in its name is still going to have to do one or the other 
(unless you're talking about a function which is just querying something about 
an array rather than manipulating it - like cmp).

So, when you have a function like replace, you have to choose whether it's going 
to do it in place or copy/slice the array. A different version of the function 
with a different name (such as replaceCopy or replaceInPlace) then deals with the 
other case. Phobos has already been going for the default of copying/slicing 
rather than doing it in-place. Given that strings _have_ to be copied or sliced 
and that strings are the most common type of array, making copying/slicing the 
default makes good sense.

It's fine if Boost wants to pick in-place as the default. That's their choice. 
They're also dealing with a different programming language with different pros and 
cons. Personally, I prefer that copying/slicing be the default if it's efficient 
enough to do so, since that promotes a functional style of programming, which is 
going to tend to be more straightforward and less error-prone, but if in-place 
mutation was going to be the normal use case (like is probably the case with 
Boost), then it's probably better to make in-place the norm, because that's the 
way that's going to be used most. However, since that's _not_ the way that's 
likely to be used most in D (due to strings having immutable elements), I really 
don't think that in-place as the default makes the most sense for D.

- Jonathan M Davis