Boost.Hana  1.2.0 Your standard library for metaprogramming

## Description

The Ring concept represents Groups that also form a Monoid under a second binary operation that distributes over the first.

A Ring is an algebraic structure built on top of a Group which requires a monoidal structure with respect to a second binary operation. This second binary operation must distribute over the first one. Specifically, a Ring is a triple (S, +, *) such that (S, +) is a Group, (S, *) is a Monoid and * distributes over +, i.e.

x * (y + z) == (x * y) + (x * z)

The second binary operation is often written * with its identity written 1, in reference to the Ring of integers under multiplication. The method names used here refer to this exact ring.

## Minimal complete definintion

one and mult satisfying the laws

## Laws

For all objects x, y, z of a Ring R, the following laws must be satisfied:

mult(x, mult(y, z)) == mult(mult(x, y), z) // associativity
mult(x, one<R>()) == x // right identity
mult(one<R>(), x) == x // left identity
mult(x, plus(y, z)) == plus(mult(x, y), mult(x, z)) // distributivity

## Refined concepts

Monoid, Group

## Concrete models

hana::integral_constant

## Free model for non-boolean arithmetic data types

A data type T is arithmetic if std::is_arithmetic<T>::value is true. For a non-boolean arithmetic data type T, a model of Ring is automatically defined by using the provided Group model and setting

mult(x, y) = (x * y)
one<T>() = static_cast<T>(1)
Note
The rationale for not providing a Ring model for bool is the same as for not providing Monoid and Group models.

## Structure-preserving functions

Let A and B be two Rings. A function f : A -> B is said to be a Ring morphism if it preserves the ring structure between A and B. Rigorously, for all objects x, y of data type A,

f(plus(x, y)) == plus(f(x), f(y))
f(mult(x, y)) == mult(f(x), f(y))
f(one<A>()) == one<B>()

Because of the Ring structure, it is easy to prove that the following will then also be satisfied:

f(zero<A>()) == zero<B>()
f(negate(x)) == negate(f(x))

which is to say that f will then also be a Group morphism. Functions with these properties interact nicely with Rings, which is why they are given such a special treatment.

## Variables

constexpr auto boost::hana::mult
Associative operation of a Ring. More...

template<typename R >
constexpr auto boost::hana::one
Identity of the Ring multiplication. More...

constexpr auto boost::hana::power
Elevate a ring element to its nth power.Specifically, power(x, n), is equivalent to multiplying x with itself n times using the Ring's multiplication. If the power is equal to zero, the Ring's identity (one) is returned. More...

## Variable Documentation

 constexpr auto boost::hana::mult

#include <boost/hana/fwd/mult.hpp>

Initial value:
= [](auto&& x, auto&& y) -> decltype(auto) {
return tag-dispatched;
}

Associative operation of a Ring.

Parameters
 x,y Two Ring elements to combine with the Ring binary operation.

## Cross-type version of the method

The mult method is "overloaded" to handle distinct data types with certain properties. Specifically, mult is defined for distinct data types A and B such that

1. A and B share a common data type C, as determined by the common metafunction
2. A, B and C are all Rings when taken individually
3. to<C> : A -> B and to<C> : B -> C are Ring-embeddings, as determined by the is_embedding metafunction.

The definition of mult for data types satisfying the above properties is obtained by setting

mult(x, y) = mult(to<C>(x), to<C>(y))

## Example

namespace hana = boost::hana;
BOOST_HANA_CONSTANT_CHECK(hana::mult(hana::int_c<3>, hana::int_c<5>) == hana::int_c<15>);
static_assert(hana::mult(4, 2) == 8, "");
int main() { }
template<typename R >
 constexpr auto boost::hana::one

#include <boost/hana/fwd/one.hpp>

Initial value:
= []() -> decltype(auto) {
return tag-dispatched;
}

Identity of the Ring multiplication.

Template Parameters
 R The tag (must be a model of Ring) of the returned identity.

## Example

namespace hana = boost::hana;
BOOST_HANA_CONSTANT_CHECK(hana::one<hana::integral_constant_tag<int>>() == hana::int_c<1>);
static_assert(hana::one<long>() == 1l, "");
int main() { }
 constexpr auto boost::hana::power

#include <boost/hana/fwd/power.hpp>

Initial value:
= [](auto&& x, auto const& n) -> decltype(auto) {
return tag-dispatched;
}

Elevate a ring element to its nth power.Specifically, power(x, n), is equivalent to multiplying x with itself n times using the Ring's multiplication. If the power is equal to zero, the Ring's identity (one) is returned.

Parameters
 x A Ring element that is elevated to its nth power. n A non-negative IntegralConstant representing the power to which x is elevated.
Note
Only the tag of x is used for tag-dispatching.