ceph/src/boost/boost/hana/fwd/concept/monoid.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::Monoid`.
   4
   5 @copyright Louis Dionne 2013-2017
   6 Distributed under the Boost Software License, Version 1.0.
   7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   8  */
   9
  10 #ifndef BOOST_HANA_FWD_CONCEPT_MONOID_HPP
  11 #define BOOST_HANA_FWD_CONCEPT_MONOID_HPP
  12
  13 #include <boost/hana/config.hpp>
  14
  15
  16 BOOST_HANA_NAMESPACE_BEGIN
  17     //! @ingroup group-concepts
  18     //! @defgroup group-Monoid Monoid
  19     //! The `Monoid` concept represents data types with an associative
  20     //! binary operation that has an identity.
  21     //!
  22     //! Specifically, a [Monoid][1] is a basic algebraic structure typically
  23     //! used in mathematics to construct more complex algebraic structures
  24     //! like `Group`s, `Ring`s and so on. They are useful in several contexts,
  25     //! notably to define the properties of numbers in a granular way. At its
  26     //! core, a `Monoid` is a set `S` of objects along with a binary operation
  27     //! (let's say `+`) that is associative and that has an identity in `S`.
  28     //! There are many examples of `Monoid`s:
  29     //! - strings with concatenation and the empty string as the identity
  30     //! - integers with addition and `0` as the identity
  31     //! - integers with multiplication and `1` as the identity
  32     //! - many others...
  33     //!
  34     //! As you can see with the integers, there are some sets that can be
  35     //! viewed as a monoid in more than one way, depending on the choice
  36     //! of the binary operation and identity. The method names used here
  37     //! refer to the monoid of integers under addition; `plus` is the binary
  38     //! operation and `zero` is the identity element of that operation.
  39     //!
  40     //!
  41     //! Minimal complete definition
  42     //! ---------------------------
  43     //! `plus` and `zero` satisfying the laws
  44     //!
  45     //!
  46     //! Laws
  47     //! ----
  48     //! For all objects `x`, `y` and `z` of a `Monoid` `M`, the following
  49     //! laws must be satisfied:
  50     //! @code
  51     //!     plus(zero<M>(), x) == x                    // left zero
  52     //!     plus(x, zero<M>()) == x                    // right zero
  53     //!     plus(x, plus(y, z)) == plus(plus(x, y), z) // associativity
  54     //! @endcode
  55     //!
  56     //!
  57     //! Concrete models
  58     //! ---------------
  59     //! `hana::integral_constant`
  60     //!
  61     //!
  62     //! Free model for non-boolean arithmetic data types
  63     //! ------------------------------------------------
  64     //! A data type `T` is arithmetic if `std::is_arithmetic<T>::%value` is
  65     //! true. For a non-boolean arithmetic data type `T`, a model of `Monoid`
  66     //! is automatically defined by setting
  67     //! @code
  68     //!     plus(x, y) = (x + y)
  69     //!     zero<T>() = static_cast<T>(0)
  70     //! @endcode
  71     //!
  72     //! > #### Rationale for not making `bool` a `Monoid` by default
  73     //! > First, it makes no sense whatsoever to define an additive `Monoid`
  74     //! > over the `bool` type. Also, it could make sense to define a `Monoid`
  75     //! > with logical conjunction or disjunction. However, C++ allows `bool`s
  76     //! > to be added, and the method names of this concept really suggest
  77     //! > addition. In line with the principle of least surprise, no model
  78     //! > is provided by default.
  79     //!
  80     //!
  81     //! Structure-preserving functions
  82     //! ------------------------------
  83     //! Let `A` and `B` be two `Monoid`s. A function `f : A -> B` is said
  84     //! to be a [Monoid morphism][2] if it preserves the monoidal structure
  85     //! between `A` and `B`. Rigorously, for all objects `x, y` of data
  86     //! type `A`,
  87     //! @code
  88     //!     f(plus(x, y)) == plus(f(x), f(y))
  89     //!     f(zero<A>()) == zero<B>()
  90     //! @endcode
  91     //! Functions with these properties interact nicely with `Monoid`s, which
  92     //! is why they are given such a special treatment.
  93     //!
  94     //!
  95     //! [1]: http://en.wikipedia.org/wiki/Monoid
  96     //! [2]: http://en.wikipedia.org/wiki/Monoid#Monoid_homomorphisms
  97     template <typename M>
  98     struct Monoid;
  99 BOOST_HANA_NAMESPACE_END
 100
 101 #endif // !BOOST_HANA_FWD_CONCEPT_MONOID_HPP