Add sample method to Array

[miv391]

I propose adding sample and sample_size methods to Array. They would work like this:

var arr := [1, 2, 3, 4]
print(arr.sample()) 
print(arr.sample_size(2))
print(arr.sample_size(10))

Output:

3
[4, 2]
[3, 4, 2, 1]

sample would return one random element of the array.
sample_size(n) would return a randomly sampled array containing n unique elements up to the size of the array.

sample_size is the more important of these two. Single sample can be get by arr[randi() % arr.size()], but I think that adding a method also for getting a single sample would be good for completeness sake. I think these kind of methods are very suitable for a game engine and they would have a lot of use.

I am making a game where I need to spawn 3 items to random free cells in a grid. A nice way to pick the 3 cells would be to collect the free cells to an array and then pick the 3 cells using sample_size method. There is a shuffle method which can be used for this. First shuffle the array and then pick 3 first items. But that would do a lot of unnecessary work as the whole array would be shuffled. A well implemented sample_size method would shuffle only 3 elements instead of all the elements.

For reference, Lodash (a Javascript library) has these sample and sampleSize functions, here is the implementation of sampleSize: https://github.com/lodash/lodash/blob/2f79053d7bc7c9c9561a30dda202b3dcd2b72b90/sampleSize.js

[Calinou]

It sounds like this can be implemented fairly effectively in GDScript. While this will be a bit slower than a C++ implementation, I don't think the performance of a GDScript implementation will end up being a bottleneck in most cases.

[miv391]

I don't think performance should be the main motivation to add sample_size method, although it is one motivation. Sampling multiple items from array is not a totally trivial task so I would guess that many user made GDScript implementations would be incorrect or inefficient or in worst cases both. shuffle is not a trivial operation either and as Wikipedia says, it is easy to make a naive and broken implementation.

I'm currently making a simple game which is a variant of connect three. The most complex piece of code is detecting the lines. If I were to implement the array sampling, that would easily be the second most complex. I'd rather use inefficient "shuffle everything and slice needed amount of items" method than implement a good sampling function myself. I have quite a lot programming experience, but a good sampling algorithm was not obvious to me. Of course, it is obvious now that I saw the Lodash implementation.

Reasons why sample_size should be Array method:

• there would be a correct implementation returning non-biases samples
• sampling items from an Array is quite a common task in games
• it would be somewhat faster than a GDScript implementation
• native Array method is nicer to use than a separate function
• sample_size is a close relative to shuffle

[miv391]

Now that the sample / pick_random is added in #3454 , how about adding the more important sample_size too.