From ee9034c50ed5dfb2d66c47ca64b0249492c33298 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 9 Mar 2021 14:02:51 -0700 Subject: [PATCH 1/3] Clarify the exact bounds of what is required for slices --- spec/API_specification/indexing.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md index ae9c5cedb..51de0d6c7 100644 --- a/spec/API_specification/indexing.md +++ b/spec/API_specification/indexing.md @@ -114,16 +114,18 @@ 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). +This specification does not require "clipping" out-of-bounds slice indices (for example, in Python slice semantics, `0:100` and `0:10` are equivalent on a list of length `10`). -_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._ -``` +As such, only the following ranges for the start and stop values of a slice are required. 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: -```{note} +- `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)`. -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). +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 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._ +_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 @@ -184,4 +186,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). -``` \ No newline at end of file +``` From 0656d7fd7fe16f9929f96044f13d4d5a8480d99b Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 14 Jun 2021 14:22:01 -0600 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Athan --- spec/API_specification/indexing.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md index 51de0d6c7..9be9ff51d 100644 --- a/spec/API_specification/indexing.md +++ b/spec/API_specification/indexing.md @@ -114,9 +114,13 @@ 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 slice indices (for example, in Python slice semantics, `0:100` and `0:10` are equivalent on a list of length `10`). +This specification does not require "clipping" out-of-bounds slice indices. -As such, only the following ranges for the start and stop values of a slice are required. 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: +```{note} + +This is in contrast to Python slice semantics where `0:100` and `0:10` are equivalent on a list of length `10`. + +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: - `i` or `j` omitted (`None`). - `-n <= i <= max(0, n - 1)`. From e85016f1912caee0e0633cb24992294d4e603a5f Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 14 Jun 2021 14:24:47 -0600 Subject: [PATCH 3/3] Fix some markdown --- spec/API_specification/indexing.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md index 9be9ff51d..74d210885 100644 --- a/spec/API_specification/indexing.md +++ b/spec/API_specification/indexing.md @@ -114,11 +114,8 @@ 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 slice indices. - -```{note} - -This is in contrast to Python slice semantics where `0:100` and `0:10` are equivalent on a list of length `10`. +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`. +``` 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: