Module permutator::copy

A module that perform everything in copy fashion. There is no Heap permutation family function in here because that function family already return a slice of value.

The additional constraint here is T must implement copy. The benefit of using this module is the input and output of each functionality will always in the same format. So there will be no &[&&&T] like in parent module when you perform a cartesian_product then combination then heap_permutation function. The downside is that if T is expensive to copy then there will be performance cost to pay.

General rule is that if type T in slice like &[T] is primitive type, this module will likely have no performance different, thus easier to use because there'll be no such ***x[0] syntax but if type T is a complex type like struct then it cannot be directly used in this module. There'll be some situation that required usage of this module. For example, in some case, a common Vec to store result from both combination result and those that is result from sequence of operation like combination then permutation. This cannot be done with the non-copy version because the result of single operation will be &[&T] but two operations will be &[&&T] which has different type. To avoid such case, create another Vec that hold every T then create another Vec that hold usize pointed to each element in prior Vec. Now we have a Vec that store primitive type thust can be used in this module. Another way to do the same thing but doesn't have an indirection like actual_data[pointers[i]] to access data is to create a Vec<&T> and every element in this Vec is just a ref to another element in Vec. Now, to access data, it's ref_vec[i]. The only restriction with later approach is T must be sized.

Note: All Iterator that return an owned item still return the same owned item, e.g. Vec

Structs

CartesianProductCellIter	Generate a cartesian product between given domains into Rc<RefCell<&mut [T]>> in an iterator style. The struct implement Iterator trait so it can be used as Iterator. The struct provide into_iter() function that return itself.
CartesianProductIterator	Generate a cartesian product between given domains in an iterator style. The struct implement Iterator trait so it can be used in Iterator style. The struct provide into_iter() function that return itself.
CartesianProductRefIter	An unsafe way to generate a cartesian product between given domains into *mut [T] in an iterator style. The struct implement Iterator trait so it can be used as Iterator. The struct provide into_iter() function that return itself.
CombinationCellIter	Deprecated
CombinationIterator	Deprecated
CombinationRefIter	Deprecated
GosperCombinationCellIter	Deprecated
GosperCombinationIterator	Deprecated
GosperCombinationRefIter	Deprecated
KPermutationCellIter	k-Permutation over data of length "n" where k must be less than n. It'll attempt to permute given data by pick k elements out of n data. It use Gosper algorithm to pick the elements. It then use Heap's algorithm to permute those k elements and return each permutation back to caller by given Rc<RefCell<&mut [&T]>> parameter to new method of KPermutationCellIter.
KPermutationIterator	k-Permutation over data of length n where k must be less than n. It'll attempt to permute given data by pick k elements out of data. It use Gosper algorithm to pick the elements. It then use Heap's algorithm to permute those k elements and return each permutation back to caller.
KPermutationRefIter	k-Permutation over data of length "n" where k must be less than n and store result into mutable pointer. It'll attempt to permute given data by pick k elements out of n data. It use Gosper algorithm to pick the elements. It then use Heap's algorithm to permute those k elements and return each permutation back to caller by given *mut [&T]>> parameter to new method of KPermutationRefIter.
LargeCombinationCellIter	Create a combination iterator. The result is lexicographic ordered if input is lexicorgraphic ordered.
LargeCombinationIterator	Create a combination iterator. The result is lexicographic ordered if input is lexicorgraphic ordered.
LargeCombinationRefIter	Create an unsafe combination iterator that return result to mutable pointer. The result is lexicographic ordered if input is lexicorgraphic ordered.
SelfCartesianProductCellIter	Generate a cartesian product on itself in an iterator style. The struct implement Iterator trait so it can be used in Iterator style. The struct provide into_iter() function that return itself.
SelfCartesianProductIterator	Generate a cartesian product on itself in an iterator style. The struct implement Iterator trait so it can be used in Iterator style. The struct provide into_iter() function that return itself.
SelfCartesianProductRefIter	Generate a cartesian product on itself in an iterator style. The struct implement Iterator trait so it can be used in Iterator style. The struct provide into_iter() function that return itself.
XPermutationCellIter	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.
XPermutationIterator	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.
XPermutationRefIter	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.

Traits

CartesianProduct	Create a cartesian product out of T. For example,
Combination	Create a combination out of T Normally, it take a [T] or Vec<T> to create a combination.
Permutation	Create a permutation iterator that permute data in place. Built-in implementation return an object of HeapPermutation for slice/array and Vec. It return an object of HeapPermutationCellIter on data type of Rc<RefCell<&mut [T]>>.

Functions

cartesian_product	Create a cartesian product over given slice. The result will be a slice of T.
cartesian_product_cell	Similar to safe cartesian_product function except the way it return the product. It return result through Rc<RefCell<>> to mutable slice of result. It'll notify caller on each new result via empty callback function.
cartesian_product_sync	Similar to safe cartesian_product function except the way it return the product. It return result through Rc<RefCell<>> to mutable slice of result. It'll notify caller on each new result via empty callback function.
combination	Deprecated
combination_cell	Deprecated
combination_sync	Deprecated
get_cartesian_for	Get a cartesian product at specific location. If objects is [1, 2, 3] and degree is 2 then all possible result is [1, 1], [1, 2], [1, 3], [2, 1], [2, 2], [2, 3], [3, 1], [3, 2], [3, 3]
get_permutation_for	Get permutation at specific location. If objects is [1, 2, 3, 4] and degree is 2 then all possible permutation will be [1, 2], [1, 3], [1, 4], [2, 1], [2, 3], [2, 4], [3, 1], [3, 2], [3, 4], [4, 1], [4, 2], [4, 3].
get_permutation_size	Calculate all possible number of permutation. It's equals to size!/(size - 1).
k_permutation	Generate k-permutation over slice of d. For example: d = &[1, 2, 3]; k = 2. The result will be [1, 2], [2, 1], [1, 3], [3, 1], [2, 3], [3, 2]
k_permutation_cell	Similar to safe k_permutation function except the way it return the permutation. It return result through mutable pointer to result assuming the pointer is valid. It'll notify caller on each new result via empty callback function.
k_permutation_sync	Similar to safe k_permutation function except the way it return the permutation. It return result through mutable pointer to result assuming the pointer is valid. It'll notify caller on each new result via empty callback function.
large_combination	Generate a r-combination from given domain and call callback function on each combination.
large_combination_cell	Generate a r-combination from given domain and call callback function on each combination.
large_combination_sync	Generate a r-combination from given domain and call callback function on each combination.
self_cartesian_product	Create a cartesian product over itself. The result will be a slice of T.
self_cartesian_product_cell	Similar to safe cartesian_product function except the way it return the product. It return result through Rc<RefCell<>> to mutable slice of result. It'll notify caller on each new result via empty callback function.
self_cartesian_product_sync	Similar to safe self_cartesian_product function except the way it return the product. It return result through Arc<RwLock<>> to mutable slice of result. It'll notify caller on each new result via empty callback function.
unsafe_cartesian_product⚠	Similar to safe cartesian_product function except the way it return the product. It return result through mutable pointer to result assuming the pointer is valid. It'll notify caller on each new result via empty callback function.
unsafe_combination⚠	Deprecated
unsafe_k_permutation⚠	Similar to safe k_permutation function except the way it return the permutation. It return result through mutable pointer to result assuming the pointer is valid. It'll notify caller on each new result via empty callback function.
unsafe_large_combination⚠	Generate a r-combination from given domain and call callback function on each combination.
unsafe_self_cartesian_product⚠	Similar to safe self_cartesian_product function except the way it return the product. It return result through mutable pointer to result assuming the pointer is valid. It'll notify caller on each new result via empty callback function.
unsafe_x_permutation⚠	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.
x_permutation	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.
x_permutation_cell	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.
x_permutation_sync	A lexicographic ordered permutation based on "Algoritm X" published by Donald E. Knuth. page 20.

Type Definitions

CartesianProductIntoCellParams	A type that represent a cartesian product of the slice over slices and return result into Rc<RefCell<&mut [&T]>> by using CartesianProductCellIter
CartesianProductIntoRefParams	A type that used exclusively for trait CartesianProduct. It return CartesianProductRefIter.
CombinationIntoCellParams	A pair of source and sink to get a sharable combination.
CombinationIntoRefParams	A pair of source and sink to get a sharable combination.
KPermutationIntoCellParams	A tuples of 3 parameters that allow Permutation trait to create k-permutation iterator from it.
KPermutationIntoRefParams	A tuple of 3 parameters that allow Permutation trait to create k-permutation ref iterator from it.
KPermutationParams	A pair of parameter that allow Permutation trait to create k-permutation iterator from it.
SelfCartesianProduct	A type that used exclusively for trait CartesianProduct. It return SelfCartesianProductIterator.
SelfCartesianProductIntoCellParams	A type that used exclusively for trait CartesianProduct. It return SelfCartesianProductCellIter.
SelfCartesianProductIntoRefParams	A type that used exclusively for trait CartesianProduct. It return SelfCartesianProductRefIter.