• CartesianProductIterator 可用于任何性能不是最关键的情况。
• CartesianProductCellIter 可用于性能和安全性都很重要的情况。
• CartesianProductRefIter 可用于性能至关重要，且安全性由调用者处理的情况。每个结构体都实现了 IteratorReset 特征。
• 使用 reset 函数而不是每次需要重新迭代时创建一个新的迭代器。

特性

修改结果很危险

大多数共享结果使用内部可变性，因此函数/结构体只借用共享结果。它仅在将要修改结果时才会进行可变借用，并在调用回调或从迭代返回结果之前立即释放借用。这意味着结果在用户端也是可变的。然而，这样做可能会导致不可预想的行为。例如：heap_permutation_cell 函数会在 Rc<RefCell<>> 中就地交换一对元素。如果用户在结果中交换值，未来的某些排列可能重复已经返回的一个。如果用户从结果中删除一些值，它将引发恐慌，因为在 heap_permutation_cell 函数中无法识别大小变化。

将结果发送到其他线程很复杂

此crate提供了两种内置方法来跨线程发送结果。这两个用例在性能方面存在强烈对立。带有 "_sync" 后缀的回调将借用结果存储到 Arc > 中，从而降低了分配额外内存和复制/克隆结果到其中的成本。每个读取借用内容的线程可能需要额外的通信开销，特别是如果它不能错过发送给它的任何数据。在这种情况下，应用以下场景

1. 函数生成新结果
2. 函数通过通道通知每个线程新结果已可用。
3. 函数阻塞，直到每个线程发送通知，表示它们都已处理完数据。

另一种方法是使用返回所有者值的迭代器，然后在每个线程上克隆该值。这更容易实现，但需要更多的内存。它将上述场景简化为

1. 迭代器返回新结果。
2. 它通过通道发送新数据通知每个线程。在不受控制的测试环境中观察到的性能表明，迭代器方式比回调快至少50%。

不安全的方式最快但最困难

这是因为所有以 "unsafe_" 前缀的函数和带有 RefIter 后缀的结构都通过可变指针返回结果，这使得它具有发送结果回最低的成本。它将所有其他工作留给用户去做。要使用它，确保在不再使用时释放内存，同步和初始化都做得恰当。原始变量所有者比用户和生成器都长寿。

示例

获取特定点的排列示例

要进入 'n' 个特定的字典序排列，

use permutator::get_cartesian_size;

get_cartesian_size(3, 2); // return 9.
get_cartesian_size(3, 3); // return 27.

use permutator::get_cartesian_for;

let nums = [1, 2, 3];
get_cartesian_for(&nums, 2, 0); // Return Ok([1, 1])
get_cartesian_for(&nums, 2, 3); // Return Ok([2, 1])
get_cartesian_for(&nums, 2, 8); // Return Ok([3, 3])
get_cartesian_for(&nums, 2, 9); // Return Err("Parameter `i` is out of bound")
get_cartesian_for(&nums, 4, 0); // Return Err("Parameter `degree` cannot be larger than size of objects")

use permutator::get_permutation_size;

get_permutation_size(3, 2); // return = 6
get_permutation_size(4, 2); // return = 12

use permutator::get_permutation_for;

let nums = [1, 2, 3, 4];
get_permutation_for(&nums, 2, 0); // return Result([1, 2])
get_permutation_for(&nums, 3, 0); // return Result([1, 2, 3])
get_permutation_for(&nums, 2, 5); // return Result([2, 4])
get_permutation_for(&nums, 2, 11); // return Result([4, 3])
get_permutation_for(&nums, 2, 12); // return Err("parameter x is outside a possible length")
get_permutation_for(&nums, 5, 0); // return Err("Insufficient number of object in parameters objects for given parameter degree")

多个数据集的笛卡尔积

从3个数据集获取笛卡尔积。

    use permutator::cartesian_product;

    cartesian_product(&[&[1, 2, 3], &[4, 5, 6], &[7, 8, 9]], |product| {
        println!("{:?}", product);
    });

或者以迭代方式执行

    use permutator::CartesianProductIterator
    use std::time::Instant;
    let data : &[&[usize]] = &[&[1, 2, 3], &[4, 5, 6], &[7, 8, 9]];
    let cart = CartesianProductIterator::new(&data);
    let mut counter = 0;
    let timer = Instant::now();

    for p in cart {
        // println!("{:?}", p);
        counter += 1;
    }

    assert_eq!(data.iter().fold(1, |cum, domain| {cum * domain.len()}), counter);
    println!("Total {} products done in {:?}", counter, timer.elapsed());

导入特质，然后跳过所有对象实例化。

    use std::time::Instant;
    use permutator::CartesianProduct;
    let data : &[&[usize]] = &[&[1, 2], &[3, 4, 5, 6], &[7, 8, 9]];
    let mut counter = 0;
    let timer = Instant::now();

    data.cart_prod.for_each(|p| {
        // println!("{:?}", p);
        counter += 1;
    });

    assert_eq!(data.iter().fold(1, |cum, domain| {cum * domain.len()}), counter);
    println!("Total {} products done in {:?}", counter, timer.elapsed());

组合迭代器示例

该结构提供两种获取组合的方法。首先它可以作为迭代器使用。其次，可以通过借用一个将存储下一个组合的可变变量手动调用 next。

// Combination iterator
use permutator::LargeCombinationIterator;
use std::time::{Instant};
let data = [1, 2, 3, 4, 5];
let combinations = LargeCombinationIterator::new(&data, 3);
let mut counter = 0;
let timer = Instant::now();

for combination in combinations {
    // uncomment a line below to print each combination
    println!("{}:{:?}", counter, combination);
    counter += 1;
}

println!("Total {} combinations in {:?}", counter, timer.elapsed());

use permutator::Combination;
use std::time::{Instant};

let data = [1, 2, 3, 4, 5];
let mut counter = 0;

let timer = Instant::now();

data.combination(3).for_each(|combination| {
    // uncomment a line below to print each combination
    println!("{}:{:?}", counter, combination);
    counter += 1;
}

println!("Total {} combinations in {:?}", counter, timer.elapsed());

迭代器风格排列示例

存在 HeapPermutationIterator 和 KPermutationIterator 结构，可以进行排列。下面是 HeapPermutationIterator 的示例。

use permutator::HeapPermutationIterator;
use std::time::{Instant};
let data = &mut [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
println!("0:{:?}", data);
let mut permutator = HeapPermutationIterator::new(data);
let timer = Instant::now();
let mut counter = 1;

for permutated in permutator {
    println!("{}:{:?}", counter, permutated);
    counter += 1;
}

// or use iterator related functional approach like line below.
// permutator.into_iter().for_each(|permutated| {counter += 1;});

println!("Done {} permutations in {:?}", counter, timer.elapsed());

迭代到 Rc>

存在 HeapPermutationCellIter 和 KPermutationCellIter 结构，提供这种功能。下面是 HeapPermutationCellIter 的示例。

use permutator::HeapPermutationCellIter;
use std::cell::RefCell;
use std::rc::Rc;
use std::time::{Instant};

let data = &mut [1, 2, 3, 4];
let result = Rc::new(RefCell::new(data));
// print original data before permutation
println!("0:{:?}", &*result.borrow());
let mut permutator = HeapPermutationCellIter::new(Rc::clone(&result));
let timer = Instant::now();
let mut counter = 1;

for _ in permutator {
    // uncomment the line below to print all possible permutation
    println!("{}:{:?}", counter, &*result.borrow());
    counter += 1;
}

println!("Done {} permutations in {:?}", counter, timer.elapsed());

下面的 KPermutationCellIter 示例

use permutator::KPermutationCellIter;
use std::cell::RefCell;
use std::rc::Rc;

let k = 3;
let data = &[1, 2, 3, 4, 5];
let mut result = vec![&data[0]; k];
let shared = Rc::new(RefCell::new(result.as_mut_slice()));

let mut kperm = KPermutationCellIter::new(data, k, Rc::clone(&shared));
for _ in kperm {
    // each permutation will be stored in `shared`
    println!("{:?}", &*shared.borrow());
}

字典序排列操作

生成[1, 2, 3]、[4, 5]、[6, 7]、[8, 9]和[10]之间的有序笛卡尔积，然后从每个笛卡尔积中生成有序的k-排列，其中k=3。

use permutator::{CartesianProduct, LargeCombinationIterator, x_permutation};

let data : &[&[u8]] = &[&[1, 2, 3], &[4, 5], &[6, 7], &[8, 9], &[10]];
let k = 3;

data.cart_prod().for_each(|cp| {
    // lexicographically ordered cartesian product in `cp`
    LargeCombinationIterator::new(&cp, k).for_each(|co| {
        // lexicographically ordered combination of length 3
        x_permutation(&co, |_| true, |p| {
            // lexicographically ordered permutation
            println!("{:?}", p);
        });
    });
});

生成[1, 2, 3]、[4, 5]、[6, 7]、[8, 9]和[10]之间的有序笛卡尔积，然后从每个笛卡尔积中生成有序的k-排列，其中k=3。此外，过滤掉所有以奇数为第一个元素的排列。

use permutator::{CartesianProduct, LargeCombinationIterator, x_permutation};

let data : &[&[u8]] = &[&[1, 2, 3], &[4, 5], &[6, 7], &[8, 9], &[10]];
let k = 3;

data.cart_prod().for_each(|cp| {
    // lexicographically ordered cartesian product in `cp`
    LargeCombinationIterator::new(&cp, k).for_each(|co| {
        // lexicographically ordered combination of length 3
        x_permutation(
            &co, 
            // first bit == 1 mean it's odd number
            // notice *** in front of v ?
            // that's because the root module always return borrowed value.
            // to get rid of this, use all operation from `copy` module
            |v| ***v[0] & 1 != 1, 
            |p| 
        {
            // lexicographically ordered permutation
            println!("{:?}", p);
        });
    });
});

为各种类型添加新功能的特点

CartesianProduct特质添加了cart_prod函数。该函数没有参数。该函数返回与通过提供的结构体返回的相同迭代器，因此可以像这个示例一样使用。

use permutator::CartesianProduct;
let data : &[&[i32]]= &[&[1, 2, 3], &[4, 5]];

data.cart_prod().for_each(|p| {
    // print all product like [1, 4], [1, 5], ...
    println!("{:?}", p);
});

或

use permutator::CartesianProduct;
let data : &[&[i32]]= &[&[1, 2, 3], &[4, 5]];
let mut result = vec![&data[0][0]; data.len()];
let shared = Rc::new(RefCell::new(result.as_mut_slice()));
// shared can be owned by anyone who want to get cartesian product.
(&data, Rc::clone(&shared)).cart_prod().for_each(|_| {
    // print all product like [1, 4], [1, 5], ...
    println!("{:?}", &*shared.borrow());
    // and notify all owner of shared object so they know that new product is available.
});

Combination特质添加了combination函数。该函数接受1个参数。它是组合框的大小，称为k、r等。该函数返回与通过提供的结构体返回的相同迭代器，因此可以像这个示例一样使用。

use permutator::Combination;
let data = [1, 2, 3, 4, 5];
data.combination(3).for_each(|comb| {
    // print all combination like [1, 2, 3], [1, 2, 4], ...
    println!("{:?}", comb);
});

或

use permutator::Combination;
let data = [1, 2, 3, 4, 5];
let k = 3;
let mut result = vec![&data[0]; k];
let shared = Rc::new(RefCell::new(result.as_mut_slice()));
// shared can be owned by anyone who want to get combinations.
(&data, Rc::clone(&shared)).combination(k).for_each(|_| {
    // print all combination like [1, 2, 3], [1, 2, 4], ...
    println!("{:?}", &*shared.borrow());
    // and notify all owner of shared object so they know that new combination is available.
});