Merge pull request #30 from LiamGoodacre/master

Default impls for Foldable & Traversable methods

Author: paf31

docs/Data/Bifoldable.md

@@ -16,6 +16,60 @@ A fold for such a structure requires two step functions, one for each type
 argument. Type class instances should choose the appropriate step function based
 on the type of the element encountered at each point of the fold.
 
+Default implementations are provided by the following functions:
+
+- `bifoldrDefault`
+- `bifoldlDefault`
+- `bifoldMapDefaultR`
+- `bifoldMapDefaultL`
+
+Note: some combinations of the default implementations are unsafe to
+use together - causing a non-terminating mutually recursive cycle.
+These combinations are documented per function.
+
+#### `bifoldrDefault`
+
+``` purescript
+bifoldrDefault :: forall p a b c. (Bifoldable p) => (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
+```
+
+A default implementation of `bifoldr` using `bifoldMap`.
+
+Note: when defining a `Bifoldable` instance, this function is unsafe to
+use in combination with `bifoldMapDefaultR`.
+
+#### `bifoldlDefault`
+
+``` purescript
+bifoldlDefault :: forall p a b c. (Bifoldable p) => (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
+```
+
+A default implementation of `bifoldl` using `bifoldMap`.
+
+Note: when defining a `Bifoldable` instance, this function is unsafe to
+use in combination with `bifoldMapDefaultL`.
+
+#### `bifoldMapDefaultR`
+
+``` purescript
+bifoldMapDefaultR :: forall p m a b. (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
+```
+
+A default implementation of `bifoldMap` using `bifoldr`.
+
+Note: when defining a `Bifoldable` instance, this function is unsafe to
+use in combination with `bifoldrDefault`.
+
+#### `bifoldMapDefaultL`
+
+``` purescript
+bifoldMapDefaultL :: forall p m a b. (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
+```
+
+A default implementation of `bifoldMap` using `bifoldl`.
+
+Note: when defining a `Bifoldable` instance, this function is unsafe to
+use in combination with `bifoldlDefault`.
 
 #### `bifold`
 

docs/Data/Bitraversable.md

@@ -15,6 +15,26 @@ A traversal for such a structure requires two functions, one for each type
 argument. Type class instances should choose the appropriate function based
 on the type of the element encountered at each point of the traversal.
 
+Default implementations are provided by the following functions:
+
+- `bitraverseDefault`
+- `bisequenceDefault`
+
+#### `bitraverseDefault`
+
+``` purescript
+bitraverseDefault :: forall t f a b c d. (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
+```
+
+A default implementation of `bitraverse` using `bisequence` and `bimap`.
+
+#### `bisequenceDefault`
+
+``` purescript
+bisequenceDefault :: forall t f a b. (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b)
+```
+
+A default implementation of `bisequence` using `bitraverse`.
 
 #### `bifor`
 

docs/Data/Foldable.md

@@ -15,6 +15,17 @@ class Foldable f where
 - `foldl` folds a structure from the left
 - `foldMap` folds a structure by accumulating values in a `Monoid`
 
+Default implementations are provided by the following functions:
+
+- `foldrDefault`
+- `foldlDefault`
+- `foldMapDefaultR`
+- `foldMapDefaultL`
+
+Note: some combinations of the default implementations are unsafe to
+use together - causing a non-terminating mutually recursive cycle.
+These combinations are documented per function.
+
 ##### Instances
 ``` purescript
 instance foldableArray :: Foldable Array
@@ -28,6 +39,50 @@ instance foldableConj :: Foldable Conj
 instance foldableMultiplicative :: Foldable Multiplicative
 ```
 
+#### `foldrDefault`
+
+``` purescript
+foldrDefault :: forall f a b. (Foldable f) => (a -> b -> b) -> b -> f a -> b
+```
+
+A default implementation of `foldr` using `foldMap`.
+
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldMapDefaultR`.
+
+#### `foldlDefault`
+
+``` purescript
+foldlDefault :: forall f a b. (Foldable f) => (b -> a -> b) -> b -> f a -> b
+```
+
+A default implementation of `foldl` using `foldMap`.
+
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldMapDefaultL`.
+
+#### `foldMapDefaultR`
+
+``` purescript
+foldMapDefaultR :: forall f a m. (Foldable f, Monoid m) => (a -> m) -> f a -> m
+```
+
+A default implementation of `foldMap` using `foldr`.
+
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldrDefault`.
+
+#### `foldMapDefaultL`
+
+``` purescript
+foldMapDefaultL :: forall f a m. (Foldable f, Monoid m) => (a -> m) -> f a -> m
+```
+
+A default implementation of `foldMap` using `foldl`.
+
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldlDefault`.
+
 #### `fold`
 
 ``` purescript

docs/Data/Traversable.md

@@ -27,6 +27,11 @@ following sense:
 
 - `foldMap f = runConst <<< traverse (Const <<< f)`
 
+Default implementations are provided by the following functions:
+
+- `traverseDefault`
+- `sequenceDefault`
+
 ##### Instances
 ``` purescript
 instance traversableArray :: Traversable Array
@@ -40,6 +45,22 @@ instance traversableDisj :: Traversable Disj
 instance traversableMultiplicative :: Traversable Multiplicative
 ```
 
+#### `traverseDefault`
+
+``` purescript
+traverseDefault :: forall t a b m. (Traversable t, Applicative m) => (a -> m b) -> t a -> m (t b)
+```
+
+A default implementation of `traverse` using `sequence` and `map`.
+
+#### `sequenceDefault`
+
+``` purescript
+sequenceDefault :: forall t a m. (Traversable t, Applicative m) => t (m a) -> m (t a)
+```
+
+A default implementation of `sequence` using `traverse`.
+
 #### `for`
 
 ``` purescript

src/Data/Bifoldable.purs

@@ -3,9 +3,11 @@ module Data.Bifoldable where
 import Prelude
 
 import Control.Apply ((*>))
-import Data.Monoid (Monoid)
+import Data.Monoid (Monoid, mempty)
 import Data.Monoid.Disj (Disj(..), runDisj)
 import Data.Monoid.Conj (Conj(..), runConj)
+import Data.Monoid.Endo (Endo(..), runEndo)
+import Data.Monoid.Dual (Dual(..), runDual)
 
 -- | `Bifoldable` represents data structures with two type arguments which can be
 -- | folded.
@@ -14,11 +16,60 @@ import Data.Monoid.Conj (Conj(..), runConj)
 -- | argument. Type class instances should choose the appropriate step function based
 -- | on the type of the element encountered at each point of the fold.
 -- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `bifoldrDefault`
+-- | - `bifoldlDefault`
+-- | - `bifoldMapDefaultR`
+-- | - `bifoldMapDefaultL`
+-- |
+-- | Note: some combinations of the default implementations are unsafe to
+-- | use together - causing a non-terminating mutually recursive cycle.
+-- | These combinations are documented per function.
 class Bifoldable p where
   bifoldr :: forall a b c. (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
   bifoldl :: forall a b c. (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
   bifoldMap :: forall m a b. (Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
 
+
+-- | A default implementation of `bifoldr` using `bifoldMap`.
+-- |
+-- | Note: when defining a `Bifoldable` instance, this function is unsafe to
+-- | use in combination with `bifoldMapDefaultR`.
+bifoldrDefault :: forall p a b c. (Bifoldable p) =>
+                  (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
+bifoldrDefault f g z p = runEndo (bifoldMap (Endo <<< f)
+                                            (Endo <<< g) p) z
+
+-- | A default implementation of `bifoldl` using `bifoldMap`.
+-- |
+-- | Note: when defining a `Bifoldable` instance, this function is unsafe to
+-- | use in combination with `bifoldMapDefaultL`.
+bifoldlDefault :: forall p a b c. (Bifoldable p) =>
+                  (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
+bifoldlDefault f g z p = runEndo (runDual
+  (bifoldMap (Dual <<< Endo <<< flip f)
+             (Dual <<< Endo <<< flip g) p)) z
+
+-- | A default implementation of `bifoldMap` using `bifoldr`.
+-- |
+-- | Note: when defining a `Bifoldable` instance, this function is unsafe to
+-- | use in combination with `bifoldrDefault`.
+bifoldMapDefaultR :: forall p m a b. (Bifoldable p, Monoid m) =>
+                     (a -> m) -> (b -> m) -> p a b -> m
+bifoldMapDefaultR f g p = bifoldr ((<>) <<< f)
+                                  ((<>) <<< g) mempty p
+
+-- | A default implementation of `bifoldMap` using `bifoldl`.
+-- |
+-- | Note: when defining a `Bifoldable` instance, this function is unsafe to
+-- | use in combination with `bifoldlDefault`.
+bifoldMapDefaultL :: forall p m a b. (Bifoldable p, Monoid m) =>
+                     (a -> m) -> (b -> m) -> p a b -> m
+bifoldMapDefaultL f g p = bifoldl (\m a -> m <> f a)
+                                  (\m b -> m <> g b) mempty p
+
+
 -- | Fold a data structure, accumulating values in a monoidal type.
 bifold :: forall t m. (Bifoldable t, Monoid m) => t m m -> m
 bifold = bifoldMap id id

src/Data/Bitraversable.purs

@@ -3,7 +3,7 @@ module Data.Bitraversable where
 import Prelude
 
 import Data.Bifoldable
-import Data.Bifunctor (Bifunctor)
+import Data.Bifunctor (Bifunctor, bimap)
 
 -- | `Bitraversable` represents data structures with two type arguments which can be
 -- | traversed.
@@ -12,10 +12,26 @@ import Data.Bifunctor (Bifunctor)
 -- | argument. Type class instances should choose the appropriate function based
 -- | on the type of the element encountered at each point of the traversal.
 -- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `bitraverseDefault`
+-- | - `bisequenceDefault`
 class (Bifunctor t, Bifoldable t) <= Bitraversable t where
   bitraverse :: forall f a b c d. (Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
   bisequence :: forall f a b. (Applicative f) => t (f a) (f b) -> f (t a b)
 
+
+-- | A default implementation of `bitraverse` using `bisequence` and `bimap`.
+bitraverseDefault :: forall t f a b c d. (Bitraversable t, Applicative f) =>
+                     (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
+bitraverseDefault f g t = bisequence (bimap f g t)
+
+-- | A default implementation of `bisequence` using `bitraverse`.
+bisequenceDefault :: forall t f a b. (Bitraversable t, Applicative f) =>
+                     t (f a) (f b) -> f (t a b)
+bisequenceDefault t = bitraverse id id t
+
+
 -- | Traverse a data structure, accumulating effects and results using an `Applicative` functor.
 bifor :: forall t f a b c d. (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d)
 bifor t f g = bitraverse f g t

src/Data/Foldable.purs

@@ -1,5 +1,6 @@
 module Data.Foldable
   ( Foldable, foldr, foldl, foldMap
+  , foldrDefault, foldlDefault, foldMapDefaultL, foldMapDefaultR
   , fold
   , traverse_
   , for_
@@ -25,7 +26,8 @@ import Data.Maybe.First (First(..), runFirst)
 import Data.Maybe.Last (Last(..))
 import Data.Monoid (Monoid, mempty)
 import Data.Monoid.Additive (Additive(..))
-import Data.Monoid.Dual (Dual(..))
+import Data.Monoid.Dual (Dual(..), runDual)
+import Data.Monoid.Endo (Endo(..), runEndo)
 import Data.Monoid.Disj (Disj(..), runDisj)
 import Data.Monoid.Conj (Conj(..), runConj)
 import Data.Monoid.Multiplicative (Multiplicative(..))
@@ -35,15 +37,60 @@ import Data.Monoid.Multiplicative (Multiplicative(..))
 -- | - `foldr` folds a structure from the right
 -- | - `foldl` folds a structure from the left
 -- | - `foldMap` folds a structure by accumulating values in a `Monoid`
+-- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `foldrDefault`
+-- | - `foldlDefault`
+-- | - `foldMapDefaultR`
+-- | - `foldMapDefaultL`
+-- |
+-- | Note: some combinations of the default implementations are unsafe to
+-- | use together - causing a non-terminating mutually recursive cycle.
+-- | These combinations are documented per function.
 class Foldable f where
   foldr :: forall a b. (a -> b -> b) -> b -> f a -> b
   foldl :: forall a b. (b -> a -> b) -> b -> f a -> b
   foldMap :: forall a m. (Monoid m) => (a -> m) -> f a -> m
 
+
+-- | A default implementation of `foldr` using `foldMap`.
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldMapDefaultR`.
+foldrDefault :: forall f a b. (Foldable f) =>
+                (a -> b -> b) -> b -> f a -> b
+foldrDefault c u xs = runEndo (foldMap (Endo <<< c) xs) u
+
+-- | A default implementation of `foldl` using `foldMap`.
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldMapDefaultL`.
+foldlDefault :: forall f a b. (Foldable f) =>
+                (b -> a -> b) -> b -> f a -> b
+foldlDefault c u xs = runEndo (runDual (foldMap (Dual <<< Endo <<< flip c) xs)) u
+
+-- | A default implementation of `foldMap` using `foldr`.
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldrDefault`.
+foldMapDefaultR :: forall f a m. (Foldable f, Monoid m) =>
+                   (a -> m) -> f a -> m
+foldMapDefaultR f xs = foldr (\x acc -> f x <> acc) mempty xs
+
+-- | A default implementation of `foldMap` using `foldl`.
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldlDefault`.
+foldMapDefaultL :: forall f a m. (Foldable f, Monoid m) =>
+                   (a -> m) -> f a -> m
+foldMapDefaultL f xs = foldl (\acc x -> f x <> acc) mempty xs
+
+
 instance foldableArray :: Foldable Array where
-  foldr = foldrArray
-  foldl = foldlArray
-  foldMap f xs = foldr (\x acc -> f x <> acc) mempty xs
+  foldr   = foldrArray
+  foldl   = foldlArray
+  foldMap = foldMapDefaultR
 
 foreign import foldrArray :: forall a b. (a -> b -> b) -> b -> Array a -> b
 foreign import foldlArray :: forall a b. (b -> a -> b) -> b -> Array a -> b