change(permute) rename function to include type

permutation type is based on order of elements
renamed iter to order_iter
renamed table to order_table

kept backward compatibility in place

lua/pl/permute.lua

@@ -12,11 +12,11 @@ local assert_arg = utils.assert_arg
 local permute = {}
 
 
---- an iterator over all permutations of the elements of a list.
+--- an iterator over all order-permutations of the elements of a list.
 -- Please note that the same list is returned each time, so do not keep references!
 -- @param a list-like table
 -- @return an iterator which provides the next permutation as a list
-function permute.iter(a)
+function permute.order_iter(a)
     assert_arg(1,a,'table')
 
     local t = #a
@@ -69,7 +69,7 @@ end
 -- @param a list-like table
 -- @return a table of tables
 -- @usage permute.table {1,2,3} --> {{2,3,1},{3,2,1},{3,1,2},{1,3,2},{2,1,3},{1,2,3}}
-function permute.table (a)
+function permute.order_table (a)
     assert_arg(1,a,'table')
     local res = {}
     for t in permute.iter(a) do
@@ -78,4 +78,22 @@ function permute.table (a)
     return res
 end
 
+
+
+-- backward compat, to be deprecated
+
+--- deprecated.
+-- @see permute.order_iter
+function permute.iter(...)
+  --TODO: add deprecation warning here
+  return permute.order_iter(...)
+end
+
+--- deprecated.
+-- @see permute.order_iter
+function permute.table(...)
+  --TODO: add deprecation warning here
+  return permute.order_table(...)
+end
+
 return permute

spec/permute_spec.lua

@@ -3,11 +3,11 @@ local tcopy = require("pl.tablex").copy
 
 describe("pl.permute", function()
 
-  describe("iter", function()
+  describe("order_iter", function()
 
     it("returns all order combinations", function()
       local result = {}
-      for list in permute.iter({"one", "two", "three"}) do
+      for list in permute.order_iter({"one", "two", "three"}) do
         result[#result+1] = tcopy(list)
       end
       assert.same({
@@ -40,7 +40,7 @@ describe("pl.permute", function()
 
     it("returns nil on empty list", function()
       local result = {}
-      for list in permute.iter({}) do
+      for list in permute.order_iter({}) do
         result[#result+1] = tcopy(list)
       end
       assert.equal(0, #result)
@@ -50,10 +50,10 @@ describe("pl.permute", function()
 
 
 
-  describe("table", function()
+  describe("order_table", function()
 
     it("returns all order combinations", function()
-      local result = permute.table({"one", "two", "three"})
+      local result = permute.order_table({"one", "two", "three"})
       assert.same({
         [1] = {
            [1] = 'two',
@@ -83,7 +83,7 @@ describe("pl.permute", function()
 
 
     it("returns empty table on empty input list", function()
-      local result = permute.table({})
+      local result = permute.order_table({})
       assert.same({}, result)
     end)