base-4.8.2.0: Basic libraries

Copyright | (c) Andy Gill 2001, (c) Oregon Graduate Institute of Science and Technology, 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | experimental
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

Data.Monoid

Contents

- `Monoid` typeclass
- `Bool` wrappers
- `Num` wrappers
- `Maybe` wrappers
- `Alternative` wrapper

Description

A class for monoids (types with an associative binary operation that has an identity) with various general-purpose instances.

Synopsis

- class Monoid a where
  - mempty :: a
  - mappend :: a -> a -> a
  - mconcat :: [a] -> a
- (<>) :: Monoid m => m -> m -> m
- newtype Dual a = Dual {
  - getDual :: a
  }
- newtype Endo a = Endo {
  - appEndo :: a -> a
  }
- newtype All = All {
  - getAll :: Bool
  }
- newtype Any = Any {
  - getAny :: Bool
  }
- newtype Sum a = Sum {
  - getSum :: a
  }
- newtype Product a = Product {
  - getProduct :: a
  }
- newtype First a = First {
  - getFirst :: Maybe a
  }
- newtype Last a = Last {
  - getLast :: Maybe a
  }
- newtype Alt f a = Alt {
  - getAlt :: f a
  }

# `Monoid` typeclass

class Monoid a where

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following laws:

-     mappend mempty x = x

-     mappend x mempty = x

-     mappend x (mappend y z) = mappend (mappend x y) z

-     mconcat = foldr mappend mempty

The method names refer to the monoid of lists under concatenation, but there are many other instances.

Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define `newtype`s and make those instances of `Monoid`, e.g. `Sum` and `Product`.

Minimal complete definition

mempty, mappend

Methods

mempty :: a

Identity of `mappend`

mappend :: a -> a -> a

An associative operation

mconcat :: [a] -> a

Fold a list using the monoid. For most types, the default definition for `mconcat` will be used, but the function is included in the class definition so that an optimized version can be provided for specific types.

Instances

Monoid Ordering |
Monoid () |
Monoid Any |
Monoid All |
Monoid Lifetime | `mappend` == `elSupremum`
Monoid Event |
Monoid [a] |
Monoid a => Monoid (Maybe a) | Lift a semigroup into `Maybe` forming a `Monoid` according to http://en.wikipedia.org/wiki/Monoid: "Any semigroup `S` may be turned into a monoid simply by adjoining an element `e` not in `S` and defining `e*e = e` and `e*s = s = s*e` for all `s ∈ S`." Since there is no "Semigroup" typeclass providing just `mappend`, we use `Monoid` instead.
Monoid (Last a) |
Monoid (First a) |
Num a => Monoid (Product a) |
Num a => Monoid (Sum a) |
Monoid (Endo a) |
Monoid a => Monoid (Dual a) |
Monoid b => Monoid (a -> b) |
(Monoid a, Monoid b) => Monoid (a, b) |
Monoid (Proxy k s) |
Monoid a => Monoid (Const a b) |
(Monoid a, Monoid b, Monoid c) => Monoid (a, b, c) |
Alternative f => Monoid (Alt * f a) |
(Monoid a, Monoid b, Monoid c, Monoid d) => Monoid (a, b, c, d) |
(Monoid a, Monoid b, Monoid c, Monoid d, Monoid e) => Monoid (a, b, c, d, e) |

(<>) :: Monoid m => m -> m -> m infixr 6

An infix synonym for `mappend`.

Since: 4.5.0.0

newtype Dual a

The dual of a `Monoid`, obtained by swapping the arguments of `mappend`.

Constructors

Dual |

Fields

getDual :: a

Instances

Generic1 Dual |
Bounded a => Bounded (Dual a) |
Eq a => Eq (Dual a) |
Ord a => Ord (Dual a) |
Read a => Read (Dual a) |
Show a => Show (Dual a) |
Generic (Dual a) |
Monoid a => Monoid (Dual a) |
type Rep1 Dual |
type Rep (Dual a) |

newtype Endo a

The monoid of endomorphisms under composition.

Constructors

Endo |

Fields

appEndo :: a -> a

Instances

Generic (Endo a) |
Monoid (Endo a) |
type Rep (Endo a) |

# `Bool` wrappers

newtype All

Boolean monoid under conjunction (`&&`).

Constructors

All |

Fields

getAll :: Bool

Instances

Bounded All |
Eq All |
Ord All |
Read All |
Show All |
Generic All |
Monoid All |
type Rep All |

newtype Any

Boolean monoid under disjunction (`||`).

Constructors

Any |

Fields

getAny :: Bool

Instances

Bounded Any |
Eq Any |
Ord Any |
Read Any |
Show Any |
Generic Any |
Monoid Any |
type Rep Any |

# `Num` wrappers

newtype Sum a

Monoid under addition.

Constructors

Sum |

Fields

getSum :: a

Instances

Generic1 Sum |
Bounded a => Bounded (Sum a) |
Eq a => Eq (Sum a) |
Num a => Num (Sum a) |
Ord a => Ord (Sum a) |
Read a => Read (Sum a) |
Show a => Show (Sum a) |
Generic (Sum a) |
Num a => Monoid (Sum a) |
type Rep1 Sum |
type Rep (Sum a) |

newtype Product a

Monoid under multiplication.

Constructors

Product |

Fields

getProduct :: a

Instances

Generic1 Product |
Bounded a => Bounded (Product a) |
Eq a => Eq (Product a) |
Num a => Num (Product a) |
Ord a => Ord (Product a) |
Read a => Read (Product a) |
Show a => Show (Product a) |
Generic (Product a) |
Num a => Monoid (Product a) |
type Rep1 Product |
type Rep (Product a) |

# `Maybe` wrappers

To implement `find` or `findLast` on any `Foldable`:

    findLast :: Foldable t => (a -> Bool) -> t a -> Maybe a
    findLast pred = getLast . foldMap (x -> if pred x
                                               then Last (Just x)
                                               else Last Nothing)

Much of Data.Map's interface can be implemented with Data.Map.alter. Some of the rest can be implemented with a new `alterA` function and either `First` or `Last`:

    alterA :: (Applicative f, Ord k) =>
              (Maybe a -> f (Maybe a)) -> k -> Map k a -> f (Map k a)

    instance Monoid a => Applicative ((,) a)  -- from Control.Applicative

    insertLookupWithKey :: Ord k => (k -> v -> v -> v) -> k -> v
                        -> Map k v -> (Maybe v, Map k v)
    insertLookupWithKey combine key value =
      Arrow.first getFirst . alterA doChange key
      where
      doChange Nothing = (First Nothing, Just value)
      doChange (Just oldValue) =
        (First (Just oldValue),
         Just (combine key value oldValue))

newtype First a

Maybe monoid returning the leftmost non-Nothing value.

``First` a` is isomorphic to ``Alt` `Maybe` a`, but precedes it historically.

Constructors

First |

Fields

getFirst :: Maybe a

Instances

Monad First |
Functor First |
Applicative First |
Generic1 First |
Eq a => Eq (First a) |
Ord a => Ord (First a) |
Read a => Read (First a) |
Show a => Show (First a) |
Generic (First a) |
Monoid (First a) |
type Rep1 First |
type Rep (First a) |

newtype Last a

Maybe monoid returning the rightmost non-Nothing value.

``Last` a` is isomorphic to ``Dual` (`First` a)`, and thus to ``Dual` (`Alt` `Maybe` a)`

Constructors

Last |

Fields

getLast :: Maybe a

Instances

Monad Last |
Functor Last |
Applicative Last |
Generic1 Last |
Eq a => Eq (Last a) |
Ord a => Ord (Last a) |
Read a => Read (Last a) |
Show a => Show (Last a) |
Generic (Last a) |
Monoid (Last a) |
type Rep1 Last |
type Rep (Last a) |

# `Alternative` wrapper

newtype Alt f a

Monoid under `<|>`.

Since: 4.8.0.0

Constructors

Alt |

Fields

getAlt :: f a

Instances

Monad f => Monad (Alt * f) |
Functor f => Functor (Alt * f) |
Applicative f => Applicative (Alt * f) |
Generic1 (Alt * f) |
MonadPlus f => MonadPlus (Alt * f) |
Alternative f => Alternative (Alt * f) |
Enum (f a) => Enum (Alt k f a) |
Eq (f a) => Eq (Alt k f a) |
Num (f a) => Num (Alt k f a) |
Ord (f a) => Ord (Alt k f a) |
Read (f a) => Read (Alt k f a) |
Show (f a) => Show (Alt k f a) |
Generic (Alt k f a) |
Alternative f => Monoid (Alt * f a) |
type Rep1 (Alt k f) |
type Rep (Alt k f a) |