Why is std.algorithm so complicated to use?

[Jacob Carlborg]

On 2012-07-16 09:18, Jonathan M Davis wrote:

> We do have InPlace in function names when one version of a function operates
> in place and another doesn't, but we haven't generally done that on functions
> which only have one version, and I don't expect that to change now (at least
> not for existing functions).

Yes, that's good. But we can always add that to the documentation. There 
can also be some general documentation about this on the top of the 
std.algorithm module. Something like:

"No function operates in place unless it explicitly says so in the 
documentation or if its name has the 'inPlace' suffix."

> In any case, _most_ range-based functions _don't_ operate in place, but it's
> certainly true that the ones that do should make that clear in their
> documentation.
>
> remove is a bit of a special case, however, in that it does the changes in
> place but doesn't take a ref, so while the return value is shortened to not
> include the removed elements, the original is just as long as it was before
> (which is useful in cases where you want to then set the elements at the end),
> and you end up with something that's sort of in place and sort of not.
> Regardless, remove is confusing enough to most people (just like erase in C++)
> that it's documentation needs to be very clear, but I don't know how good it
> is or isn't. Given the difficulty of explaining it properly and Merhdad's
> confusion, it probably stands to be improved.

Just _because_ of how "remove" works in std.algorithm and "erase" in 
C++, I though "sort" behaved similar.

-- 
/Jacob Carlborg