godotengine / godotengine/godot-docs

Array class API: backport Array.slice() description from 4.x to 3.x

Open
#5,621 0 comments 0 reactions 0 assignees View on GitHub
area:class reference enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.