Re: [eigen] On a flexible API for submatrices, slicing, indexing, maskin

On Wed, Jan 4, 2017 at 2:32 PM, Yuanchen Zhu <yuanchen.zhu@xxxxxxxxx> wrote:

Still I'd say that changing the case to avoid a name collision is against most sane coding conventions, especially when the particular coding convention uses case to differentiate between the type of the name.

To tell you the truth, I don't feel comfortable in introducing a "Size" function... it's just that the respective size/length/count/etc. property should be accessible through a 'size' function for consistency, and thus it feels odd not to call the respective argument 'size/Size'. I would thus rather try to make the option (A) below works out...

Some more ideas for option (A). Suppose we define xxx(first, last, incr). Suffix it with "n" or "N" for the version that takes in (first, len, incr). Examples:

seq(3, 3+n-1, 2) <-> seqn(3, n, 2) or seqN(3, n, 2) or seq_n(3, n, 2) (more STL like)

Likewise:

aseq(3, 3+n-1, 2) <-> aseqn(3, n, 2) or aseqN(3, n, 2)
aprog(3, 3+n-1, 2) <-> aprogn(3, n, 2) or aprogN(a, n, 2)
ap(3, 3+n-1, 2) <-> apn(3, n, 2) or apN(a, n, 2)

The letter "n" serves as a mnemonic for length. This way, we don't have to remember which is the bounded version and which is sized version. The C++ standard library sets the precedents with its "_n" suffixed algorithms, e.g., copy vs copy_n, find vs find_n. A single undercase "n" as a suffix doesn't work too well for longer word like "span" or "range" though.

The aseq/seqn pair looks pretty good. seq/seqn might be acceptable too, though a sequence can mean a lot of different things, especially if you take the union of its usage in both math and CS!

Then regarding aseqn vs aseqN, the upper-case might be welcome to make the difference more prominent and reduce the risk of misuse?

I've added them in the wiki. I've also added several other suggestions, for instance:

fromto(i,j[,incr])

fromfor(i,n[,incr])

In the wiki you will also see an experiment (variant C) with a programmatic API (the length-based version was already there, but the bound-based version is relatively new). This is mostly for fun, but it does have several merits. In particular it avoids endless discussions on functions names (well you still need a fews), parameter arguments, inclusive/exclusive bounds, etc. In any case, I think we need to provide something like option "A" anyway because it is more suited to be also used as a complement to LinSpaced:

VectorXi v = aseq(...);

Fixed<V>

This and the shorter "Fix" are both nice. I still prefer the all lower case version though, since it's a function and there's no name collision.

yes, my favorites so far are: ic<N>, fix<N>, fixed<N>

I also want to revisit the ordering of first, last, and the (optional) incr parameters. We have these existing conventions:

- Matlab/Julia: (first, [incr,] last)
- Numpy: (first, end [, incr]), and also indices can be negative numbers

As you can see, it matches neither.

the first,last[,incr] convention is not new:

- Fortran,

- S-Lang,

- Mathematica

- boost::irange

- R: seq()

- Swift: stride()

- and probably more

I fail to see a good reason why we shouldn't just adopt Matlab's convention of (first, incr, last), similar to libigl's colon(), so that there's one few set of convention to remember.

A strong argument is that in C++ optional parameters usually go last. Moreover, we also need to be consistant between the two variants, and aseqn(first,incr,size) would be really new, whereas many functions/language follows the (first,size,incr) order.

Martlab aficionados are still free to declare "auto colon(first,incr,last) { return aseq(first,last,incr)); }", and done.

BTW, regarding inclusive vs exclusive upper bound, python's users seem to have several arguments, all grounded on the zero-based indexing thing: http://stackoverflow.com/questions/11364533/why-are-slice-and-range-upper-bound-exclusive.

gael