Undocumented behavior on numel for multiple inputs

The numel function only accepts one input argument according to its documentation. However, it can also accept multiple input arguments with behavior that seems to be similar to numel at times, similar to nnz at other times, and with errors at still other times.

For example, with 1-by-4 arrays of doubles:

clear; clc
d1 = [0 0 1 0];
d2 = [0 1 1 1];
numel(d1, d1) % ans = 4
numel(d2, d2) % ans = 4
numel(d1, d2) % ans = 4

The same syntax produces different behavior with 1-by-4 arrays of logicals:

clear; clc
d1 = logical([0 0 1 0]);
d2 = logical([0 1 1 1]);
numel(d1, d1) % ans = 1, also equal to nnz(d1)
numel(d2, d2) % ans = 3, also equal to nnz(d2)
numel(d1, d2) % ans = 3

The same syntax produces errors with 1-by-4 cell arrays:

clear; clc
d1 = {0 0 1 0};
d2 = {0 1 1 1};
numel(d1, d1) % errors
numel(d2, d2) % errors
numel(d1, d2) % errors

I haven't tested every possible data type but I think these examples already demonstrate undocumented behavior. The documentation also notes that the output of numel is equivalent to prod(size(A)), but it's not clear from this behavior whether this is true for multiple inputs or, if it is, how the second input argument is handled.

Perhaps the documentation for numel could be updated to better describe how multiple inputs are handled.

Answer 1

[Walter Roberson]

Undocumented behaviour can be anything and would not be a bug. I would not expect Mathworks to change anything.

Hypothesize that you took the first input and wanted to know how big the output would be if you were to index it by the remaining arguments, ignoring the possibility of elements out of range or non-integer.

• any argument from the second on that was not numeric or logical would be an error
• any numeric argument from the second on would contribute an index component equal to the number of elements it had
• any logical argument from the second on would contribute an index component equal to the number of true elements it had
• the implied final size would be the product of all of these values.

Thus, numel(X, s1, s2, s3, ...) would answer the question of how many elements X(s1,s2,s3,...) would have, provided that all of the s1, s2, s3... turn out to be in range.

[Aaron Drews]

I agree that it's not a bug (I didn't claim it to be) but I disagree that there's not room for improvement, especially in something as easily edited as documentation.

[Walter Roberson]

Documented behaviour must be maintained (or officially revoked.) Undocumented behavior can change without notice. Using undocumented behaviour is always at your own risk, and is always left up to you to figure out the boundaries of.