Merge pull request #259 from hx2A/fix199

random_sample() and random_choice() methods

py5_docs/Reference/api_en/Sketch_random_choice.txt

@@ -5,15 +5,13 @@ category = math
 subcategory = random
 
 @@ signatures
-random_choice(objects: list[Any], size: int=1, replace: bool=True) -> Any
+random_choice(objects: list[Any]) -> Any
 
 @@ variables
 objects: list[Any] - list of objects to choose from
-replace: bool=True - whether to select random items with or without replacement
-size: int=1 - number of random items to select
 
 @@ description
-Select random items from a list. The list items can be of any type. If multiple items are selected, this function will by default allow the same item to be selected multiple times. Set the `replace` parameter to `False` to prevent the same item from being selected multiple times.
+Select a random item from a list. The list items can be of any type. If the list of objects is empty, `None` will be returned.
 
 This function's randomness can be influenced by [](sketch_random_seed), and makes calls to numpy to select the random items.
 

py5_docs/Reference/api_en/Sketch_random_sample.txt

@@ -0,0 +1,26 @@
+@@ meta
+name = random_sample()
+type = method
+category = math
+subcategory = random
+
+@@ signatures
+random_sample(objects: list[Any], size: int=1, replace: bool=True) -> npt.NDArray
+
+@@ variables
+objects: list[Any] - list of objects to choose from
+replace: bool=True - whether to select random items with or without replacement
+size: int=1 - number of random items to select
+
+@@ description
+Select random items from a list. The list items can be of any type. If multiple items are selected, this function will by default allow the same item to be selected multiple times. Set the `replace` parameter to `False` to prevent the same item from being selected multiple times.
+
+The returned value will always be a numpy array, even if only one item is sampled. If the list of objects is empty, an empty numpy array will be returned.
+
+This function's randomness can be influenced by [](sketch_random_seed), and makes calls to numpy to select the random items.
+
+@@ example
+def setup():
+    words = ["apple", "bear", "cat", "dog"]
+    word = py5.random_sample(words)
+    py5.println(word)  # Prints one of the four words

py5_resources/data/sketch.csv

@@ -365,6 +365,7 @@ norm,norm,,static method,math,calculation,PYTHON,implemented in mixin file math.
 random_gaussian,randomGaussian,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 random_int,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 random_choice,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
+random_sample,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 random_seed,randomSeed,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 np_random,,,dynamic variable,math,random,PYTHON,make numpy random number generator available to users
 noise_array,noiseArray,,method,math,random,SKIP,vectorized noise for better performance

py5_resources/py5_module/py5/mixins/math.py

@@ -259,9 +259,19 @@ def random_int(self, *args: int) -> int:
         types = ','.join([type(a).__name__ for a in args])
         raise TypeError(f'No matching overloads found for Sketch.random_int({types})')
 
-    def random_choice(self, objects: list[Any], size: int=1, replace: bool=True) -> Any:
+    def random_choice(self, objects: list[Any]) -> Any:
         """$class_Sketch_random_choice"""
-        return self._rng.choice(objects, size=size, replace=replace)
+        if objects:
+            return objects[self._rng.integers(0, len(objects))]
+        else:
+            return None
+
+    def random_sample(self, objects: list[Any], size: int=1, replace: bool=True) -> npt.NDArray:
+        """$class_Sketch_random_sample"""
+        if objects:
+            return self._rng.choice(objects, size=size, replace=replace)
+        else:
+            return np.array([], dtype='O')
 
     @overload
     def random_gaussian(self) -> float: