godotengine / godotengine/godot-docs
Array class API: backport Array.slice() description from 4.x to 3.x
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:** Godot 3.4.2 stable, Godot 4 alpha2
**Issue description:**
Since Godot 3.2 we have the long sought after slice() method for Arrays (hurray!)
Unfortunately the description in the stable branch is very jargon heavy, rendering informative only for only experienced programmers:
```
Array slice ( int begin, int end, int step=1, bool deep=false )
Duplicates the subset described in the function and returns it in an array, deeply copying the array if deep is true. Lower and upper index are inclusive, with the step describing the change between indices while slicing.
```
The description on the latest branch however is much more inclusive and explicit, rendering it informative for a much wider group of Godot users:
```
Array slice ( int begin, int end=2147483647, int step=1, bool deep=false ) const
Returns the slice of the Array, from begin (inclusive) to end (exclusive), as a new Array.
The absolute value of begin and end will be clamped to the array size, so the default value for end makes it slice to the size of the array by default (i.e. arr.slice(1) is a shorthand for arr.slice(1, arr.size())).
If either begin or end are negative, they will be relative to the end of the array (i.e. arr.slice(0, -2) is a shorthand for arr.slice(0, arr.size() - 2)).
If specified, step is the relative index between source elements. It can be negative, then begin must be higher than end. For example, [0, 1, 2, 3, 4, 5].slice(5, 1, -2) returns [5, 3]).
If deep is true, each element will be copied by value rather than by reference.
```
I'm not sure whether there are any differences between the stable version method and the latest version method (such as with stable both begin and end are inclusive and in the latest only begin is inclusive, as well as the end integer limit), but if so these differences should be of course considered.
**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/stable/classes/class_array.html#class-array-method-slice
https://docs.godotengine.org/en/latest/classes/class_array.html#class-array-method-slice
Contributor guide
No contributing guide indexed for this repository
Research direction
Compare the stable and latest Array.slice() documentation at the two linked class_array.html pages, starting with the method signature and description. Confirm which behavior applies to Godot 3.x, especially the inclusive or exclusive end index and default end value. Update the stable description so it accurately and clearly documents the method.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- godot
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100