Add table.shuffle (#8299)

diff --git a/builtin/common/misc_helpers.lua b/builtin/common/misc_helpers.lua
index e4c7f4aa322f8c1134234363bd91bd4893bfaa03..1e9a08851fe9a2a653a125f68e760365549eced1 100644 (file)
--- 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 80b694ee97c142af4435360f65fb4dc299b072a8..6b8dcb5fcc4af2d0f4e8300a3e9f1c957d45f932 100644 (file)
--- 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