interpreter: Add a slice() method to arrays

This can come in handy for instance when a custom target creates both
headers and sources. Slicing the output of a `to_list()` call provides
convenient access to just the headers or just the sources.

2 files changed, 30 insertions, 0 deletions

diff --git a/docs/markdown/snippets/array-slice.md b/docs/markdown/snippets/array-slice.md
new file mode 100644
index 000000000..8b503bce9
--- /dev/null
+++ b/docs/markdown/snippets/array-slice.md
@@ -0,0 +1,3 @@
+## Array `.slice()` method
+
+Arrays now have a `.slice()` method which allows for subsetting of arrays.
diff --git a/docs/yaml/elementary/array.yml b/docs/yaml/elementary/array.yml
index 7d0480a04..7183d1aff 100644
--- a/docs/yaml/elementary/array.yml
+++ b/docs/yaml/elementary/array.yml
@@ -37,6 +37,33 @@ methods:
       type: any
       description: Fallback value that is returned if the index is out of range.
 
+- name: slice
+  returns: array[any]
+  since: 1.10.0
+  description: |
+    Return a selection of the elements of the array starting at index `start`
+    and continuing with `step` size jumps until `stop`. Negative indices count
+    from the back of the array. The step size cannot be zero, but may be
+    negative. If it is negative, `start` and `stop` default to the end and
+    beginning of the array, respectively. If `step` is positive, `start`
+    defaults to 0 and `stop` defaults to the length of the array. Either both
+    or none of `start` and `stop` must be provided to prevent ambiguity.
+
+  optargs:
+    start:
+      type: int
+      description: The lower bound of the slice
+
+    stop:
+      type: int
+      description: The upper bound of the slice
+
+  kwargs:
+    step:
+      type: int
+      default: 1
+      description: The step size
+
 - name: length
   returns: int
   description: Returns the current size of the array.