Add table.shuffle (#8299)

2 files changed, 21 insertions, 0 deletions

diff --git a/builtin/common/misc_helpers.lua b/builtin/common/misc_helpers.lua
index e4c7f4aa3..1e9a08851 100644
--- a/builtin/common/misc_helpers.lua
+++ b/builtin/common/misc_helpers.lua
@@ -576,6 +576,20 @@ function table.key_value_swap(t)
 end
 
 
+function table.shuffle(t, from, to, random)
+	from = from or 1
+	to = to or #t
+	random = random or math.random
+	local n = to - from + 1
+	while n > 1 do
+		local r = from + n-1
+		local l = from + random(0, n-1)
+		t[l], t[r] = t[r], t[l]
+		n = n-1
+	end
+end
+
+
 --------------------------------------------------------------------------------
 -- mainmenu only functions
 --------------------------------------------------------------------------------
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 80b694ee9..6b8dcb5fc 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2925,6 +2925,13 @@ Helper functions
       find new indices.
 * `table.key_value_swap(t)`: returns a table with keys and values swapped
     * If multiple keys in `t` map to the same value, the result is undefined.
+* `table.shuffle(table, [from], [to], [random_func])`:
+    * Shuffles elements `from` to `to` in `table` in place
+    * `from` defaults to `1`
+    * `to` defaults to `#table`
+    * `random_func` defaults to `math.random`. This function receives two
+      integers as arguments and should return a random integer inclusively
+      between them.
 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
   position.
     * returns the exact position on the surface of a pointed node