Re: liboctave capacity, length, nemel, and numel

[Carnë Draug]

>On 21 May 2015 at 20:04, John W. Eaton <address@hidden> wrote:
>> On 05/21/2015 01:56 PM, Carnë Draug wrote:
>>
>>> at the moment, we have 4 Array:: methods to get the current number of
>>> elements.  They are capacity, length, nemel, and numel.  What's the idea
>>> behind them?  Are subclasses supposed to overload some of them
>>> differently?
>>> I couldn't find any documentation for that.
>>>
>>> We recently got a bug about Array::length not behaving the same length()
>>> at
>>> the interpreter, which I think makes sense.  Changing the behaviour of
>>> Array::length() would be bad for backwards compatibility but maybe not
>>> having it at all would be a good idea.
>>>
>>> Just like we deprecate stuff at the Octave interpreter because there's
>>> other
>>> functions that do the same thing, should we be doing the same in
>>> liboctave?
>>
>>
>> Long ago, I think there was the idea that capacity might mean something
>> different from length if the allocated size of the underlying array was
>> different from the current number of elements that were "in use".
>>
>> I think numel was introduced just so the name could match numel from Matlab.
>>
>> I don't know why nelem (number of elements) was introduced.
>>
>> Since they all currently mean the same thing, I don't have a problem
>> deprecating all but one.  I guess at this point it would be best to keep
>> numel and (eventually) remove the rest.
>
>
> It might be worth checking in the Sparse array implementation to make
> utterly certain that there is no difference between numel and capacity; it's
> there that I would expect to find a difference if it exists.

Indeed, Sparse does have a special meaning for capacity() (amount of storage
for non-zero elements [1]) but is the same as nzmax() so it could also be
deprecated there.

> Otherwise, I really support cleaning things up.  C++ isn't meant to be an
> evocative language rich with nearly identical words.  In English I can
> compliment a woman by calling her attractive, beautiful, pretty, comely,
> etc.  It's nice to have that flexibility in the spoken language, but I'm not
> romancing my computer and I find it confusing that the same procedure could
> be called out by four different names.
>
> A minor wish is that eventually the C++ code can look close to the standard
> m-file syntax and that anyone who knows Octave syntax would be able to read,
> at least for understanding, what is happening in the C++ code.  For that
> reason, I also would preserve numel() since it mirrors the Octave language.
>
> Also, you can use the GCC_ATTR_DEPRECATED at the end of a function, like
> capacity, that will eventually be removed.  This produces a nice warning
> when code that uses it is compiled.  It would certainly be a good thing to
> put that in place and use the warnings to weed out any instances in the
> core.
>

I have started doing this and started by removing nelem.  One thing I
noticed is that Range has nelem() only.  As part of your wish of making it
closer to the standard m-syntax I replaced it with numel()  (I have not
pushed this in case anyone is against it).  A small bother of this is that
octave binary files still save this as "OCTAVE_RANGE_NELEM" [2].

Carnë

[1] http://octave.sourceforge.net/doxygen39/db/d2b/Sparse_8h_source.html#l00247
[2] 
http://hg.savannah.gnu.org/hgweb/octave/file/b5d2f6954c48/libinterp/octave-value/ov-range.cc#l593