Add a new table.shuffle extension for use in the benchmark scripts (and elsewhere)

Benchmarks/base64-decode.lua

@@ -66,14 +66,7 @@ local availableBenchmarks = {
 	end,
 }
 
-local function shuffle(tbl)
-	for i = #tbl, 2, -1 do
-		local j = math.random(i)
-		tbl[i], tbl[j] = tbl[j], tbl[i]
-	end
-end
-
-shuffle(availableBenchmarks)
+table.shuffle(availableBenchmarks)
 
 for _, benchmark in ipairs(availableBenchmarks) do
 	benchmark()

Benchmarks/base64-encode.lua

@@ -56,14 +56,7 @@ local availableBenchmarks = {
 	end,
 }
 
-local function shuffle(tbl)
-	for i = #tbl, 2, -1 do
-		local j = math.random(i)
-		tbl[i], tbl[j] = tbl[j], tbl[i]
-	end
-end
-
-shuffle(availableBenchmarks)
+table.shuffle(availableBenchmarks)
 
 for _, benchmark in ipairs(availableBenchmarks) do
 	benchmark()

Benchmarks/cpp-ffi-bitops.lua

@@ -64,14 +64,7 @@ local availableBenchmarks = {
 	end,
 }
 
-local function shuffle(tbl)
-	for i = #tbl, 2, -1 do
-		local j = math.random(i)
-		tbl[i], tbl[j] = tbl[j], tbl[i]
-	end
-end
-
-shuffle(availableBenchmarks)
+table.shuffle(availableBenchmarks)
 
 for _, benchmark in ipairs(availableBenchmarks) do
 	benchmark()

Runtime/Extensions/tablex.lua

@@ -101,5 +101,25 @@ function table.values(table)
 	return values
 end
 
+function table.shuffle(tableToShuffle, randomNumberGenerator, seed)
+	validation.validateTable(tableToShuffle, "tableToShuffle")
+
+	randomNumberGenerator = randomNumberGenerator or math.random
+	seed = seed or math.randomseed
+
+	validation.validateFunction(randomNumberGenerator, "randomNumberGenerator")
+	validation.validateFunction(seed, "seed")
+
+	seed(os.clock()) -- Good enough, for now?
+	local shuffledTable = {}
+	for i = 1, #tableToShuffle, 1 do
+		local j = randomNumberGenerator(i)
+		shuffledTable[i] = tableToShuffle[j]
+		shuffledTable[j] = tableToShuffle[i]
+	end
+
+	return shuffledTable
+end
+
 table.clear = require("table.clear")
 table.new = require("table.new")

Tests/BDD/table-library.spec.lua

@@ -197,4 +197,44 @@ describe("table", function()
 			assertTrue(table.contains(values, "world"))
 		end)
 	end)
+
+	describe("shuffle", function()
+		it("should throw if a non-table value was passed as the first parameter", function()
+			assertThrows(function()
+				table.shuffle(nil)
+			end, "Expected argument tableToShuffle to be a table value, but received a nil value instead")
+		end)
+
+		it("should throw if a non-function value was passed as the second parameter", function()
+			assertThrows(function()
+				table.shuffle({}, 42)
+			end, "Expected argument randomNumberGenerator to be a function value, but received a number value instead")
+		end)
+
+		it("should throw if a non-function value was passed as the third parameter", function()
+			assertThrows(function()
+				table.shuffle({}, math.random, 42)
+			end, "Expected argument seed to be a function value, but received a number value instead")
+		end)
+
+		it("should randomize the given table using the provided generator and seed", function()
+			local randomSequence = {}
+			local initialValue = 0
+			local numGeneratedValues = 0
+			local function generator()
+				local nextPseudoRandomNumber = initialValue - numGeneratedValues
+				numGeneratedValues = numGeneratedValues + 1
+				table.insert(randomSequence, nextPseudoRandomNumber)
+				return nextPseudoRandomNumber
+			end
+
+			local tableToShuffle = { 1, 2, 3 }
+			local function seed(clock)
+				initialValue = #tableToShuffle
+			end
+
+			local shuffledTable = table.shuffle(tableToShuffle, generator, seed)
+			assertEquals(shuffledTable, { 3, 2, 1 })
+		end)
+	end)
 end)