Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify the exact bounds of what is required for slices #138

Merged
merged 3 commits into from
Sep 20, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions spec/API_specification/indexing.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,16 +114,19 @@ Using a slice to index a single array axis must adhere to the following rules. L

```{note}

This specification does not require "clipping" out-of-bounds indices (i.e., requiring the starting and stopping indices `i` and `j` be bound by `0` and `n`, respectively).

_Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations._
This specification does not require "clipping" out-of-bounds slice indices. This is in contrast to Python slice semantics where `0:100` and `0:10` are equivalent on a list of length `10`.
```

```{note}
The following ranges for the start and stop values of a slice must be supported. Let `n` be the axis (dimension) size being sliced. For a slice `i:j:k`, the behavior specified above should be implemented for the following:

This specification leaves unspecified the behavior of indexing a single array axis with an out-of-bounds slice (i.e., a slice which does not select any array axis elements).
- `i` or `j` omitted (`None`).
- `-n <= i <= max(0, n - 1)`.
- For `k > 0` or `k` omitted (`None`), `-n <= j <= n`.
- For `k < 0`, `-n - 1 <= j <= max(0, n - 1)`.

_Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to return an empty array (whose axis (dimension) size along the indexed axis is `0`), raise an exception, or some other behavior depending on device requirements and performance considerations._
The behavior outside of these bounds is unspecified.

_Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip (consistent with Python `list` slicing semantics), raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations._
```

## Multi-axis Indexing
Expand Down Expand Up @@ -184,4 +187,4 @@ The result of an indexing operation (e.g., multi-axis indexing, boolean array in
```{note}

The specified return value behavior includes indexing operations which return a single value (e.g., accessing a single element within a one-dimensional array).
```
```