Repository: rust-itertools/itertools (language: rust)

Issue:
Add a note about how to permute with replacement
Currently, trying to get 'permutations with replacement', it's hard to find in the documentation how to do that. I eventually found on the github from the issue about adding permutations how `repeat_n(iter, iter.len()).multi_cartesian_product()` can do what I want, but it would be nice if this was mentioned in the docs, either on `permutations` or as a search alias on `multi_cartesian_product`.

Alternatively, it might be nice to have `permutation_with_replacement`, but I'm not sure if that's common enough that it's desired in the API.


Discussion / hints:
This was exactly what I needed as well, and was no where near obvious on how to achieve.

This is a very common use case, I would imagine, as it's a necessary step for computing the probability of rolling sum s on n dice and other similar probability calculations.

Fix patch:
diff --git a/src/lib.rs b/src/lib.rs
index 3d5f05c4f..c8422f531 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1676,6 +1676,9 @@ pub trait Itertools: Iterator {
     /// If `k` is greater than the length of the input iterator, the resultant
     /// iterator adaptor will be empty.
     ///
+    /// If you are looking for permutations with replacements,
+    /// use `repeat_n(iter, k).multi_cartesian_product()` instead.
+    ///
     /// ```
     /// use itertools::Itertools;
     ///


Test patch: