Rename group' to groupAll and add groupAllBy; add docs

src/Data/Array/NonEmpty.purs

@@ -66,8 +66,10 @@ module Data.Array.NonEmpty
   , dropWhile
   , span
   , group
+  , groupAll
   , group'
   , groupBy
+  , groupAllBy
 
   , nub
   , nubBy
@@ -118,6 +120,7 @@ import Data.Tuple (Tuple(..))
 import Data.Unfoldable (class Unfoldable)
 import Data.Unfoldable1 (class Unfoldable1, unfoldr1)
 import Partial.Unsafe (unsafePartial)
+import Prim.TypeError (class Warn, Text)
 import Unsafe.Coerce (unsafeCoerce)
 
 -- | Internal - adapt an Array transform to NonEmptyArray
@@ -350,15 +353,49 @@ span
   -> { init :: Array a, rest :: Array a }
 span f = adaptAny $ A.span f
 
+-- | Group equal, consecutive elements of an array into arrays.
+-- |
+-- | ```purescript
+-- | group (NonEmptyArray [1, 1, 2, 2, 1]) ==
+-- |   NonEmptyArray [NonEmptyArray [1, 1], NonEmptyArray [2, 2], NonEmptyArray [1]]
+-- | ```
 group :: forall a. Eq a => NonEmptyArray a -> NonEmptyArray (NonEmptyArray a)
 group = unsafeAdapt $ A.group
 
-group' :: forall a. Ord a => NonEmptyArray a -> NonEmptyArray (NonEmptyArray a)
+-- | Group equal elements of an array into arrays.
+-- |
+-- | ```purescript
+-- | groupAll (NonEmptyArray [1, 1, 2, 2, 1]) ==
+-- |   NonEmptyArray [NonEmptyArray [1, 1, 1], NonEmptyArray [2, 2]]
+-- | `
+groupAll :: forall a. Ord a => NonEmptyArray a -> NonEmptyArray (NonEmptyArray a)
+groupAll = groupAllBy eq
+
+-- | Deprecated previous name of `groupAll`.
+group' :: forall a. Warn (Text "'group\'' is deprecated, use groupAll instead") => Ord a => NonEmptyArray a -> NonEmptyArray (NonEmptyArray a)
 group' = unsafeAdapt $ A.group'
 
+-- | Group equal, consecutive elements of an array into arrays, using the
+-- | specified equivalence relation to determine equality.
+-- |
+-- | ```purescript
+-- | groupBy (\a b -> odd a && odd b) (NonEmptyArray [1, 3, 2, 4, 3, 3])
+-- |    = NonEmptyArray [NonEmptyArray [1, 3], NonEmptyArray [2], NonEmptyArray [4], NonEmptyArray [3, 3]]
+-- | ```
+-- |
 groupBy :: forall a. (a -> a -> Boolean) -> NonEmptyArray a -> NonEmptyArray (NonEmptyArray a)
 groupBy op = unsafeAdapt $ A.groupBy op
 
+-- | Group equal elements of an array into arrays, using the specified
+-- | equivalence relation to determine equality.
+-- |
+-- | ```purescript
+-- | groupAllBy (\a b -> odd a && odd b) (NonEmptyArray [1, 3, 2, 4, 3])
+-- |    = NonEmptyArray [NonEmptyArray [1], NonEmptyArray [2], NonEmptyArray [3, 3], NonEmptyArray [4]]
+-- | ```
+groupAllBy :: forall a. Ord a => (a -> a -> Boolean) -> NonEmptyArray a -> NonEmptyArray (NonEmptyArray a)
+groupAllBy op = unsafeAdapt $ A.groupAllBy op
+
 nub :: forall a. Ord a => NonEmptyArray a -> NonEmptyArray a
 nub = unsafeAdapt A.nub
 

test/Test/Data/Array/NonEmpty.purs

@@ -25,6 +25,9 @@ testNonEmptyArray = do
   let fromArray :: forall a. Array a -> NEA.NonEmptyArray a
       fromArray = unsafePartial fromJust <<< NEA.fromArray
 
+      nea :: forall a. Array a -> NEA.NonEmptyArray a
+      nea = fromArray
+
   log "singleton should construct an array with a single value"
   assert $ NEA.toArray (NEA.singleton 1) == [1]
   assert $ NEA.toArray (NEA.singleton "foo") == ["foo"]
@@ -247,15 +250,21 @@ testNonEmptyArray = do
   log "group should group consecutive equal elements into arrays"
   assert $ NEA.group (fromArray [1, 2, 2, 3, 3, 3, 1]) == fromArray [NEA.singleton 1, fromArray [2, 2], fromArray [3, 3, 3], NEA.singleton 1]
 
-  log "group' should sort then group consecutive equal elements into arrays"
-  assert $ NEA.group' (fromArray [1, 2, 2, 3, 3, 3, 1]) == fromArray [fromArray [1, 1], fromArray [2, 2], fromArray [3, 3, 3]]
+  log "groupAll should group equal elements into arrays"
+  assert $ NEA.groupAll (fromArray [1, 2, 2, 3, 3, 3, 1]) == fromArray [fromArray [1, 1], fromArray [2, 2], fromArray [3, 3, 3]]
 
   log "groupBy should group consecutive equal elements into arrays based on an equivalence relation"
   assert $ NEA.groupBy (\x y -> odd x && odd y) (fromArray [1, 1, 2, 2, 3, 3]) == fromArray [fromArray [1, 1], NEA.singleton 2, NEA.singleton 2, fromArray [3, 3]]
 
   log "groupBy should be stable"
   assert $ NEA.groupBy (\_ _ -> true) (fromArray [1, 2, 3]) == fromArray [fromArray [1, 2, 3]]
 
+  log "groupAllBy should group equal elements into arrays based on an equivalence relation"
+  assert $ NEA.groupAllBy (\x y -> odd x && odd y) (fromArray [1, 3, 2, 4, 3, 3]) == fromArray [nea [1], nea [2], nea [3, 3, 3], nea [4]]
+
+  log "groupAllBy should be stable"
+  assert $ NEA.groupAllBy (\_ _ -> true) (fromArray [1, 2, 3]) == fromArray [nea [1, 2, 3]]
+
   log "nub should remove duplicate elements from the list, keeping the first occurence"
   assert $ NEA.nub (fromArray [1, 2, 2, 3, 4, 1]) == fromArray [1, 2, 3, 4]