# Module `pl.permute`

Permutation operations.

Dependencies: pl.utils, pl.tablex

## Functions

order_iter (a) | an iterator over all order-permutations of the elements of a list.
order_table (a) | construct a table containing all the order-permutations of a list.
list_iter (...) | an iterator over all permutations of the elements of the given lists.
list_table (...) | construct a table containing all the permutations of a set of lists.
iter (...) | deprecated.
table (...) | deprecated.

## Functions

order_iter (a)
  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!

  ### Parameters:

  - a list-like table

  ### Returns:

  an iterator which provides the next permutation as a list
order_table (a)
  construct a table containing all the order-permutations of a list.

  ### Parameters:

  - a list-like table

  ### Returns:

  a table of tables

  ### Usage:

      permute.order_table {1,2,3} --> {{2,3,1},{3,2,1},{3,1,2},{1,3,2},{2,1,3},{1,2,3}}

list_iter (...)
  an iterator over all permutations of the elements of the given lists.

  ### Parameters:

  - ... list-like tables, they are nil-safe if a length-field `n` is provided (see utils.pack)

  ### Returns:

  an iterator which provides the next permutation as return values in the same order as the provided lists, preceded by an index

  ### Usage:

      local strs = utils.pack("one", nil, "three")  -- adds an 'n' field for nil-safety
      local bools = utils.pack(true, false)
      local iter = permute.list_iter(strs, bools)

      print(iter())    --> 1, one, true
      print(iter())    --> 2, nil, true
      print(iter())    --> 3, three, true
      print(iter())    --> 4, one, false
      print(iter())    --> 5, nil, false
      print(iter())    --> 6, three, false

list_table (...)
  construct a table containing all the permutations of a set of lists.

  ### Parameters:

  - ... list-like tables, they are nil-safe if a length-field `n` is provided

  ### Returns:

  a list of lists, the sub-lists have an 'n' field for nil-safety

  ### Usage:

      local strs = utils.pack("one", nil, "three")  -- adds an 'n' field for nil-safety
      local bools = utils.pack(true, false)
      local results = permute.list_table(strs, bools)
      -- results = {
      --   { "one, true, n = 2 }
      --   { nil, true, n = 2 },
      --   { "three, true, n = 2 },
      --   { "one, false, n = 2 },
      --   { nil, false, n = 2 },
      --   { "three", false, n = 2 },
      -- }

iter (...)
  deprecated.

  ### Parameters:

  - ...

  ### See also:

  permute.order_iter
table (...)
  deprecated.

  ### Parameters:

  - ...

  ### See also:

  permute.order_iter

generated by LDoc 1.5.0