Changed lume.shuffle() to not operate in-place, updated doc + tests

README.md

@@ -75,7 +75,7 @@ lume.weightedchoice({ ["cat"] = 10, ["dog"] = 5, ["frog"] = 0 })
 ```
 
 ### lume.shuffle(t)
-Shuffles the values of array `t` in place, returns the array.
+Returns a shuffled copy of the array `t`.
 
 ### lume.array(...)
 Iterates the supplied iterator and returns an array filled with the values.

lume.lua

@@ -146,11 +146,15 @@ end
 
 
 function lume.shuffle(t)
+  local rtn = {}
   for i = 1, #t do
-    local r = math_random(#t)
-    t[i], t[r] = t[r], t[i]
+    local r = math_random(i)
+    if r ~= i then
+      rtn[i] = rtn[r]
+    end
+    rtn[r] = t[i]
   end
-  return t
+  return rtn
 end
 
 

test/test_lume.lua

@@ -109,7 +109,7 @@ end
 -- lume.shuffle
 tests["lume.shuffle"] = function()
   local t = {1, 2, 3, 4, 5}
-  lume.shuffle(t)
+  t = lume.shuffle(t)
   table.sort(t)
   testeq( t,                {1, 2, 3, 4, 5} )
   testeq( lume.shuffle({}), {}              )