Add -WithIndex classes (#72)

* Add -WithIndex classes

This adds `FunctorWithIndex`, `FoldableWithIndex` and
`TraversableWithIndex` and some combinators. Implementations are mostly
copied from the versions without index with minor adaptions. Similarly
for the documentation.

I think the corresponding haskell package does not state all laws for
these type classes, so there are TODO's in the doc strings of the three
classes.

`StateL` and `StateR` in TraversableWithIndex.purs are exact copies of
the versions in Traversable.purs because they are not exported there.
Maybe it would be better to merge TraversableWithIndex.purs into
Traversable.purs and similarly for Foldable. The Foldable and Traverse
instances of Array could then be along the lines of
```purescript
traverse f = itraverse (const f)`
```
so that the foreign js imports for the unindexed version could be
removed.

`FunctorWithIndex`'s `imap` collides with the `imap` of
purescript-invariant. Haskell calls the latter `invmap`. I don't know
whether that's a problem.

This does not yet include the `-1WithIndex` classes, i.e.
generalizations of `Foldable1` and `Traversable1` in `Semigroup/`. I
guess it would make sense to provide them here as well.

* Fix export lists

* Add missing semicolon in js

* Remove foreign implementation of array's itraverse

* Move `Accum` and State to separate module

* Remove foreign implementation of array's folds

* Settle with incomplete laws

The modified `Foldable` and `Traversable` laws that must hold for their
-WithIndex versions are missing in the docs. But because the actual
unmodified laws for `Foldable` and `Traversable` themselves are not here
either I guess it shouldn't be a problem.

* Add some test for FoldableWithIndex

No tests for

- ifoldM
- itraverse_
- ifor_
- iall
- iany
- all instances except for Array

These are not tested for Foldable either.

* Add test for Array's TraversableWithIndex instance

* Fix name: Add mising i- prefix

* Change index naming scheme `i-` -> `-WithIndex`

* Revert accidentally renamed Bifoldable functions

Author: Martin Bidlingmaier

src/Data/FoldableWithIndex.purs

@@ -0,0 +1,273 @@
+module Data.FoldableWithIndex
+  ( class FoldableWithIndex, foldrWithIndex, foldlWithIndex, foldMapWithIndex
+  , foldrWithIndexDefault
+  , foldlWithIndexDefault
+  , foldMapWithIndexDefaultR
+  , foldMapWithIndexDefaultL
+  , foldWithIndexM
+  , traverseWithIndex_
+  , forWithIndex_
+  , surroundMapWithIndex
+  , allWithIndex
+  , anyWithIndex
+  , findWithIndex
+  ) where
+
+import Prelude
+
+import Data.Foldable (class Foldable, foldMap, foldl, foldr)
+import Data.FunctorWithIndex (mapWithIndex)
+import Data.Maybe (Maybe(..))
+import Data.Maybe.First (First)
+import Data.Maybe.Last (Last)
+import Data.Monoid (class Monoid, mempty)
+import Data.Monoid.Additive (Additive)
+import Data.Monoid.Conj (Conj(..))
+import Data.Monoid.Disj (Disj(..))
+import Data.Monoid.Dual (Dual(..))
+import Data.Monoid.Endo (Endo(..))
+import Data.Monoid.Multiplicative (Multiplicative)
+import Data.Newtype (unwrap)
+
+-- | A `Foldable` with an additional index.  
+-- | A `FoldableWithIndex` instance must be compatible with its `Foldable`
+-- | instance
+-- | ```purescript
+-- | foldr f = foldrWithIndex (const f)
+-- | foldl f = foldlWithIndex (const f)
+-- | foldMap f = foldMapWithIndex (const f)
+-- | ```
+-- | 
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `foldrWithIndexDefault`
+-- | - `foldlWithIndexDefault`
+-- | - `foldMapWithIndexDefaultR`
+-- | - `foldMapWithIndexDefaultL`
+-- |
+-- | 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 <= FoldableWithIndex i f | f -> i where
+  foldrWithIndex :: forall a b. (i -> a -> b -> b) -> b -> f a -> b
+  foldlWithIndex :: forall a b. (i -> b -> a -> b) -> b -> f a -> b
+  foldMapWithIndex :: forall a m. Monoid m => (i -> a -> m) -> f a -> m
+
+-- | A default implementation of `foldrWithIndex` using `foldMapWithIndex`.
+-- |
+-- | Note: when defining a `FoldableWithIndex` instance, this function is
+-- | unsafe to use in combination with `foldMapWithIndexDefaultR`.
+foldrWithIndexDefault
+  :: forall i f a b
+   . FoldableWithIndex i f
+  => (i -> a -> b -> b)
+  -> b
+  -> f a
+  -> b
+foldrWithIndexDefault c u xs = unwrap (foldMapWithIndex (\i -> Endo <<< c i) xs) u
+
+-- | A default implementation of `foldlWithIndex` using `foldMapWithIndex`.
+-- |
+-- | Note: when defining a `FoldableWithIndex` instance, this function is
+-- | unsafe to use in combination with `foldMapWithIndexDefaultL`.
+foldlWithIndexDefault
+  :: forall i f a b
+   . FoldableWithIndex i f
+  => (i -> b -> a -> b)
+  -> b
+  -> f a
+  -> b
+foldlWithIndexDefault c u xs = unwrap (unwrap (foldMapWithIndex (\i -> Dual <<< Endo <<< flip (c i)) xs)) u
+
+-- | A default implementation of `foldMapWithIndex` using `foldrWithIndex`.
+-- |
+-- | Note: when defining a `FoldableWithIndex` instance, this function is
+-- | unsafe to use in combination with `foldrWithIndexDefault`.
+foldMapWithIndexDefaultR
+  :: forall i f a m
+   . FoldableWithIndex i f
+  => Monoid m
+  => (i -> a -> m)
+  -> f a
+  -> m
+foldMapWithIndexDefaultR f = foldrWithIndex (\i x acc -> f i x <> acc) mempty
+
+-- | A default implementation of `foldMapWithIndex` using `foldlWithIndex`.
+-- |
+-- | Note: when defining a `FoldableWithIndex` instance, this function is
+-- | unsafe to use in combination with `foldlWithIndexDefault`.
+foldMapWithIndexDefaultL
+  :: forall i f a m
+   . FoldableWithIndex i f
+  => Monoid m
+  => (i -> a -> m)
+  -> f a
+  -> m
+foldMapWithIndexDefaultL f = foldlWithIndex (\i acc x -> acc <> f i x) mempty
+
+data Tuple a b = Tuple a b
+
+instance foldableWithIndexArray :: FoldableWithIndex Int Array where
+  foldrWithIndex f z = foldr (\(Tuple i x) y -> f i x y) z <<< mapWithIndex Tuple
+  foldlWithIndex f z = foldl (\y (Tuple i x) -> f i y x) z <<< mapWithIndex Tuple
+  foldMapWithIndex = foldMapWithIndexDefaultR
+
+instance foldableWithIndexMaybe :: FoldableWithIndex Unit Maybe where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexFirst :: FoldableWithIndex Unit First where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexLast :: FoldableWithIndex Unit Last where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexAdditive :: FoldableWithIndex Unit Additive where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexDual :: FoldableWithIndex Unit Dual where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexDisj :: FoldableWithIndex Unit Disj where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexConj :: FoldableWithIndex Unit Conj where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+instance foldableWithIndexMultiplicative :: FoldableWithIndex Unit Multiplicative where
+  foldrWithIndex f = foldr $ f unit
+  foldlWithIndex f = foldl $ f unit
+  foldMapWithIndex f = foldMap $ f unit
+
+
+-- | Similar to 'foldlWithIndex', but the result is encapsulated in a monad. 
+-- |
+-- | Note: this function is not generally stack-safe, e.g., for monads which 
+-- | build up thunks a la `Eff`.
+foldWithIndexM
+  :: forall i f m a b
+   . FoldableWithIndex i f
+  => Monad m
+  => (i -> a -> b -> m a)
+  -> a
+  -> f b
+  -> m a
+foldWithIndexM f a0 = foldlWithIndex (\i ma b -> ma >>= flip (f i) b) (pure a0)
+
+-- | Traverse a data structure with access to the index, performing some
+-- | effects encoded by an `Applicative` functor at each value, ignoring the
+-- | final result.
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | > traverseWithIndex_ (curry logShow) ["a", "b", "c"]
+-- | (Tuple 0 "a")
+-- | (Tuple 1 "b")
+-- | (Tuple 2 "c")
+-- | ```
+traverseWithIndex_
+  :: forall i a b f m
+   . Applicative m
+  => FoldableWithIndex i f
+  => (i -> a -> m b)
+  -> f a
+  -> m Unit
+traverseWithIndex_ f = foldrWithIndex (\i -> (*>) <<< f i) (pure unit)
+
+-- | A version of `traverseWithIndex_` with its arguments flipped.
+-- |
+-- | This can be useful when running an action written using do notation
+-- | for every element in a data structure:
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | forWithIndex_ ["a", "b", "c"] \i x -> do
+-- |   logShow i
+-- |   log x
+-- | ```
+forWithIndex_
+  :: forall i a b f m
+   . Applicative m
+  => FoldableWithIndex i f
+  => f a
+  -> (i -> a -> m b)
+  -> m Unit
+forWithIndex_ = flip traverseWithIndex_
+
+-- | `foldMapWithIndex` but with each element surrounded by some fixed value.
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | > surroundMapWithIndex "*" (\i x -> show i <> x) []
+-- | = "*"
+-- |
+-- | > surroundMapWithIndex "*" (\i x -> show i <> x) ["a"]
+-- | = "*0a*"
+-- |
+-- | > surroundMapWithIndex "*" (\i x -> show i <> x) ["a", "b"]
+-- | = "*0a*1b*"
+-- |
+-- | > surroundMapWithIndex "*" (\i x -> show i <> x) ["a", "b", "c"]
+-- | = "*0a*1b*2c*"
+-- | ```
+surroundMapWithIndex
+  :: forall i f a m
+   . FoldableWithIndex i f
+  => Semigroup m
+  => m
+  -> (i -> a -> m)
+  -> f a
+  -> m
+surroundMapWithIndex d t f = unwrap (foldMapWithIndex joined f) d
+  where joined i a = Endo \m -> d <> t i a <> m
+
+-- | `allWithIndex f` is the same as `and <<< mapWithIndex f`; map a function over the
+-- | structure, and then get the conjunction of the results.
+allWithIndex
+  :: forall i a b f
+   . FoldableWithIndex i f
+  => HeytingAlgebra b
+  => (i -> a -> b)
+  -> f a
+  -> b
+allWithIndex t = unwrap <<< foldMapWithIndex (\i -> Conj <<< t i)
+
+-- | `anyWithIndex f` is the same as `or <<< mapWithIndex f`; map a function over the
+-- | structure, and then get the disjunction of the results.
+anyWithIndex
+  :: forall i a b f
+   . FoldableWithIndex i f
+  => HeytingAlgebra b
+  => (i -> a -> b)
+  -> f a
+  -> b
+anyWithIndex t = unwrap <<< foldMapWithIndex (\i -> Disj <<< t i)
+
+-- | Try to find an element in a data structure which satisfies a predicate
+-- | with access to the index.
+findWithIndex
+  :: forall i a f
+   . FoldableWithIndex i f
+  => (i -> a -> Boolean)
+  -> f a
+  -> Maybe a
+findWithIndex p = foldlWithIndex go Nothing
+  where
+  go i Nothing x | p i x = Just x
+  go i r _ = r

src/Data/FunctorWithIndex.js

@@ -0,0 +1,12 @@
+"use strict";
+
+exports.mapWithIndexArray = function (f) {
+  return function (xs) {
+    var l = xs.length;
+    var result = Array(l);
+    for (var i = 0; i < l; i++) {
+      result[i] = f(i)(xs[i]);
+    }
+    return result;
+  };
+};

src/Data/FunctorWithIndex.purs

@@ -0,0 +1,57 @@
+module Data.FunctorWithIndex
+  ( class FunctorWithIndex, mapWithIndex
+  ) where
+
+import Prelude
+
+import Data.Maybe (Maybe)
+import Data.Maybe.First (First)
+import Data.Maybe.Last (Last)
+import Data.Monoid.Additive (Additive)
+import Data.Monoid.Conj (Conj)
+import Data.Monoid.Disj (Disj)
+import Data.Monoid.Dual (Dual)
+import Data.Monoid.Multiplicative (Multiplicative)
+
+
+-- | A `Functor` with an additional index.  
+-- | Instances must satisfy a modified form of the `Functor` laws
+-- | ```purescript
+-- | mapWithIndex (\_ a -> a) = id
+-- | mapWithIndex f . mapWithIndex g = mapWithIndex (\i -> f i <<< g i)
+-- | ```
+-- | and be compatible with the `Functor` instance
+-- | ```purescript
+-- | map f = mapWithIndex (const f)
+-- | ```
+class Functor f <= FunctorWithIndex i f | f -> i where
+  mapWithIndex :: forall a b. (i -> a -> b) -> f a -> f b
+
+foreign import mapWithIndexArray :: forall i a b. (i -> a -> b) -> Array a -> Array b
+
+instance functorWithIndexArray :: FunctorWithIndex Int Array where
+  mapWithIndex = mapWithIndexArray
+
+instance functorWithIndexMaybe :: FunctorWithIndex Unit Maybe where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexFirst :: FunctorWithIndex Unit First where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexLast :: FunctorWithIndex Unit Last where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexAdditive :: FunctorWithIndex Unit Additive where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexDual :: FunctorWithIndex Unit Dual where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexConj :: FunctorWithIndex Unit Conj where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexDisj :: FunctorWithIndex Unit Disj where
+  mapWithIndex f = map $ f unit
+
+instance functorWithIndexMultiplicative :: FunctorWithIndex Unit Multiplicative where
+  mapWithIndex f = map $ f unit