Add clarification for single to multi index conversion

[saulshanabrook]

I wanted to add a clarification to the indexing guide that any single-axis index (i.e. x[10]) is semantically equivalent to a multi-axis index with a single element (i.e. x[10,]).

This does not include boolean indexing, however. I thought that was clear since it is under a different heading than "single-axis indexing" but I could also make it explicit.

I assume this is actually true! If not, then this PR can be disregarded.

[asmeurer]

Isn't this already what the first sentence here says?

[saulshanabrook]

Do you mean this sentence?

In Python, A[(exp1, exp2, ..., expN)] is equivalent to A[exp1, exp2, ..., expN]; the latter is syntactic sugar for the former.

If so, I read it as saying something slightly different, more about the python AST parser than any semantics specifics to array indexing? i.e. I read it it as saying that x[y,] is the same as x[(y,)] not that x[y] is not the same as x[y,].

If you meant this one:

Accordingly, if A has rank 1, then A[(2:10,)] must be equivalent to A[2:10]. If A has rank 2, then A[(2:10, :)] must be equivalent to A[2:10, :]. And so on and so forth.

It also reads slightly differently to me, in that it only specifies full indexing of an array, i.e. it doesn't say that A[(2:10,)] is equivalent to A[2:10] for any array, only those with rank 1.

[asmeurer]

I was referring to that second sentence. Actually it is supposed to say only for rank 1, because we decided to only specify indexing when every axis is explicitly indexed (or an ellipsis is used). So a[2:10] is actually not specified unless a is 1-D (and neither is a[2:10,]). If a is 3-D, for instance, you have to do a[2:10, :, :] or a[2:10, ...]. (FWIW, I personally was not a fan of this decision, but that's what the consortium decided).

I think that this is spelled out in the document but maybe it could be clearer.

[saulshanabrook]

Oh wow, I wasn't aware of that.

I'll close this PR then.

Doing a closer reading of the indexing spec I think this bullet point covers your point:

Except in the case of providing a single ellipsis (e.g., A[2:10, ...] or A[1:, ..., 2:5]), the number of provided single-axis indexing expressions (excluding None) should equal N. For example, if A has rank 2, a single-axis indexing expression should be explicitly provided for both axes (e.g., A[2:10, :]). An IndexError exception should be raised if the number of provided single-axis indexing expressions (excluding None) is less than N.

[saulshanabrook]

Thanks for your clarifications @asmeurer!