[Numpy-discussion] sort documentation

[Robert Kern]

On Sun, Aug 31, 2008 at 09:33, dmitrey <dmitrey.kroshko at scipy.org> wrote:
> As for me I can't understand the general rule: when numpy funcs return
> copy and when reference?

It's driven by use cases and limitations of the particular functions.

> For example why x.fill() returns None (do inplace modification) while
> x.ravel(), x.flatten() returns copy? Why the latters don't do inplace
> modification, as should be expected?

That example does not go with the question that you asked, but the
reason is that we need a way to quickly set all elements of an array
to the same value. The entire use case for that feature is in-place
modification. For example, suppose that I want an array of a given
shape with all of its values being 2.0.

  x = numpy.empty(shape)
  x.fill(2.0)

If .fill() were to make a copy, then I've just wasted memory, possibly
quite a lot.

For .ravel() and .flatten(), we can't modify the object in-place in
many instances. Ravelling or flattening simply can't be done in-place
for non-contiguous arrays. New memory needs to be allocated and data
copied. That's intrinsically not an operation that can be done
in-place.

Now, to your original question, why some functions return views and
some return copies. The difference between .ravel() and .flatten() is
that .ravel() returns a view when it can and copies when it must while
.flatten() always allocates new memory. The difference is driven by
use cases. Sometimes, you will not be modifying the raveled array, and
you just need an object with the right shape and data as fast as
possible. So when possible, .ravel() returns a view. However, there
are use cases when you do need to modify the flattened array
afterwards without affecting the original, so we have .flatten(). It
will consistently return new memory, so it can be modified freely.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
 -- Umberto Eco