[Numpy-discussion] rationalizing functions that return number of elements

[Russell E Owen]

I'm hoping we might rationalize the names of functions that return 
the number of elements in an array and fix the associated help 
strings. At present we have:

numarray function size(array, axis=None)
   Seems to return # of elements in array, or in a particular axis,
   but its help says something else:
   "size  returns the size in bytes of an array."

numarray.ma has function size(a, axis=None)
   Seems the same as numarray.size but the help is wrong,
   and in a different way:
   "returns shape tuple for 'a'.  MaskedArray version."

nummarray.ma arrays have method "size(seolf, axis=None):
   The same as the others and correctly documented:
   "Number of elements in array, or in a particular axis."

numarray arrays have method nelements()
   The same as "size" above, but has no axis argument:
   "nelements() -> total number of elements in array."

I strongly encourage you to settle on one name (and one
argument list, i.e. with "axis"). The current situation
forces one to treat ma arrays differently than normal arrays
in an area where there's no need for such a difference.
It is also confusing.

"size" is a perfectly good name and is already used
in 3 out of 4 cases, so adopting it will break the
least existing code and deprecate only one odd method.

On the other hand, "nelements" has the advantage
that it is less ambiguous (based on the incorrect help
strings). So if you really think it's worth the pain
you could switch to that.

My personal leaning is towards "size", but it's not
my decision.

By the way, "itemsize" already exists as an
array method, so "size" is NOT needed for that
(and would be a wretched choice--ambigious and
the potential to mysteriously break existing code).

-- Russell

P.S. I reported "nelements" as PR 934514
<http://sourceforge.net/tracker/index.php?func=detail&aid=934514&group_id=1369&atid=450446>
and the incorrect help strings as PR 944678
<http://sourceforge.net/tracker/index.php?func=detail&aid=944678&group_id=1369&atid=450446>

P.P.S. here's a log showing the tests that convinced me size works as 
I said, not as the help strings say:
>>>  a = num.array([[1.1, 2.2, 3.3], [4.4, 5.5, 6.6]])
>>>  a
array([[ 1.1,  2.2,  3.3],
        [ 4.4,  5.5,  6.6]])
>>>  numarray.size(a)
6
>>>  numarray.size(a, 1)
3
>>>  aa = numarray.ma.array(a)
>>>  numarray.ma.size(aa)
6
>>>  numarray.ma.size(aa, 1)
3
>>>  aa.size()
6
>>>  aa.size(1)
3
>>>  a.nelements()
6