Add changelog + @since for next/prevPermutation

This adds a changelog entry and `@since` annotations for:
- Optimization of `Data.Vector.Generic.Mutable.nextPermutation`
- Addition of `Data.Vector.Generic.Mutable.prevPermutation(By)`
- Addition of `Data.Vector.Generic.Mutable.nextPermutationBy`

This also tweaks the haddock comments of the functions for
`Data.Vector.*.Mutable.(next|prev)Permutation(By)?` for a better
readability.

Author: gksato

vector/changelog.md

@@ -1,3 +1,13 @@
+# Changes in version 0.13.2.0
+
+ * We had some improvements on `*.Mutable.{next,prev}Permutation{,By}`
+   [#498](https://github.com/haskell/vector/pull/498):
+   * Add `*.Mutable.prevPermutation{,By}` and `*.Mutable.nextPermutationBy`
+   * Improve time performance. We may now expect good specialization supported by inlining.
+     The implementation has also been algorithmically updated: in the previous implementation
+     the full enumeration of all the permutations of `[1..n]` took Omega(n*n!), but it now takes O(n!).
+   * Add tests for `{next,prev}Permutation`
+
 # Changes in version 0.13.1.0
 
  * Specialized variants of `findIndexR` are reexported for all vector

vector/src/Data/Vector/Generic/Mutable.hs

@@ -1217,35 +1217,41 @@ partitionWithUnknown f s
 
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
 nextPermutation :: (PrimMonad m, Ord e, MVector v e) => v (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = nextPermutationByLt (<)
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
+--
+-- @since 0.13.2.0
 nextPermutationBy :: (PrimMonad m, MVector v e) => (e -> e -> Ordering) -> v (PrimState m) e -> m Bool
 {-# INLINE nextPermutationBy #-}
 nextPermutationBy cmp = nextPermutationByLt (\x y -> cmp x y == LT)
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutation :: (PrimMonad m, Ord e, MVector v e) => v (PrimState m) e -> m Bool
 {-# INLINE prevPermutation #-}
 prevPermutation = nextPermutationByLt (>)
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutationBy :: (PrimMonad m, MVector v e) => (e -> e -> Ordering) -> v (PrimState m) e -> m Bool
 {-# INLINE prevPermutationBy #-}
 prevPermutationBy cmp = nextPermutationByLt (\x y -> cmp x y == GT)

vector/src/Data/Vector/Mutable.hs

@@ -575,35 +575,41 @@ unsafeMove = G.unsafeMove
 -- -----------------
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
 nextPermutation :: (PrimMonad m, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
+--
+-- @since 0.13.2.0
 nextPermutationBy :: PrimMonad m => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutationBy #-}
 nextPermutationBy = G.nextPermutationBy
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutation :: (PrimMonad m, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutation #-}
 prevPermutation = G.prevPermutation
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutationBy :: PrimMonad m => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutationBy #-}
 prevPermutationBy = G.prevPermutationBy

vector/src/Data/Vector/Primitive/Mutable.hs

@@ -541,35 +541,41 @@ unsafeMove = G.unsafeMove
 -- -----------------
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
 nextPermutation :: (PrimMonad m,Ord e,Prim e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
+--
+-- @since 0.13.2.0
 nextPermutationBy :: (PrimMonad m,Prim e) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutationBy #-}
 nextPermutationBy = G.nextPermutationBy
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutation :: (PrimMonad m,Ord e,Prim e) => MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutation #-}
 prevPermutation = G.prevPermutation
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutationBy :: (PrimMonad m,Prim e) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutationBy #-}
 prevPermutationBy = G.prevPermutationBy

vector/src/Data/Vector/Storable/Mutable.hs

@@ -642,35 +642,41 @@ unsafeMove = G.unsafeMove
 -- -----------------
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
 nextPermutation :: (PrimMonad m, Storable e, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
+--
+-- @since 0.13.2.0
 nextPermutationBy :: (PrimMonad m, Storable e) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutationBy #-}
 nextPermutationBy = G.nextPermutationBy
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutation :: (PrimMonad m, Storable e, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutation #-}
 prevPermutation = G.prevPermutation
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutationBy :: (PrimMonad m, Storable e) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutationBy #-}
 prevPermutationBy = G.prevPermutationBy

vector/src/Data/Vector/Strict/Mutable.hs

@@ -555,9 +555,9 @@ unsafeMove = G.unsafeMove
 -- -----------------
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
 --
 -- @since 0.13.2.0
 nextPermutation :: (PrimMonad m, Ord e) => MVector (PrimState m) e -> m Bool
@@ -566,27 +566,33 @@ nextPermutation = G.nextPermutation
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
-nextPermutationBy :: (PrimMonad m) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
+--
+-- @since 0.13.2.0
+nextPermutationBy :: PrimMonad m => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutationBy #-}
 nextPermutationBy = G.nextPermutationBy
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutation :: (PrimMonad m, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutation #-}
 prevPermutation = G.prevPermutation
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
-prevPermutationBy :: (PrimMonad m) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
+prevPermutationBy :: PrimMonad m => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutationBy #-}
 prevPermutationBy = G.prevPermutationBy
 

vector/src/Data/Vector/Unboxed/Mutable.hs

@@ -444,35 +444,41 @@ unsafeMove = G.unsafeMove
 -- -----------------
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
 nextPermutation :: (PrimMonad m,Ord e,Unbox e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
 -- | Compute the (lexicographically) next permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly descending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::next_permutation@.
+--
+-- @since 0.13.2.0
 nextPermutationBy :: (PrimMonad m,Unbox e) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutationBy #-}
 nextPermutationBy = G.nextPermutationBy
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutation :: (PrimMonad m,Ord e,Unbox e) => MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutation #-}
 prevPermutation = G.prevPermutation
 
 -- | Compute the (lexicographically) previous permutation of the given vector in-place,
 -- using the provided comparison function.
--- Returns False when the input is the last permutation; in this case the vector
--- will not get updated, as opposed to the behavior of the C++ function 
--- @std::next_permutation@.
+-- Returns False when the input is the last item in the enumeration, i.e., if it is in
+-- weakly ascending order. In this case the vector will not get updated,
+-- as opposed to the behavior of the C++ function @std::prev_permutation@.
+--
+-- @since 0.13.2.0
 prevPermutationBy :: (PrimMonad m,Unbox e) => (e -> e -> Ordering) -> MVector (PrimState m) e -> m Bool
 {-# INLINE prevPermutationBy #-}
 prevPermutationBy = G.prevPermutationBy