EIC code displayed by LXR master/​include/​boost/​hana/​fwd/​concept/​constant.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 09:37:58

 /*!
 @file
 Forward declares `boost::hana::Constant`.
 
 Copyright Louis Dionne 2013-2022
 Distributed under the Boost Software License, Version 1.0.
 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
  */
 
 #ifndef BOOST_HANA_FWD_CONCEPT_CONSTANT_HPP
 #define BOOST_HANA_FWD_CONCEPT_CONSTANT_HPP
 
 #include <boost/hana/config.hpp>
 
 
 namespace boost { namespace hana {
     //! @ingroup group-concepts
     //! @defgroup group-Constant Constant
     //! The `Constant` concept represents data that can be manipulated at
     //! compile-time.
     //!
     //! At its core, `Constant` is simply a generalization of the principle
     //! behind `std::integral_constant` to all types that can be constructed
     //! at compile-time, i.e. to all types with a `constexpr` constructor
     //! (also called [Literal types][1]). More specifically, a `Constant` is
     //! an object from which a `constexpr` value may be obtained (through the
     //! `value` method) regardless of the `constexpr`ness of the object itself.
     //!
     //! All `Constant`s must be somewhat equivalent, in the following sense.
     //! Let `C(T)` and `D(U)` denote the tags of `Constant`s holding objects
     //! of type `T` and `U`, respectively. Then, an object with tag `D(U)`
     //! must be convertible to an object with tag `C(T)` whenever `U` is
     //! convertible to `T`, as determined by `is_convertible`. The
     //! interpretation here is that a `Constant` is just a box holding
     //! an object of some type, and it should be possible to swap between
     //! boxes whenever the objects inside the boxes can be swapped.
     //!
     //! Because of this last requirement, one could be tempted to think that
     //! specialized "boxes" like `std::integral_constant` are prevented from
     //! being `Constant`s because they are not able to hold objects of any
     //! type `T` (`std::integral_constant` may only hold integral types).
     //! This is false; the requirement should be interpreted as saying that
     //! whenever `C(T)` is _meaningful_ (e.g. only when `T` is integral for
     //! `std::integral_constant`) _and_ there exists a conversion from `U`
     //! to `T`, then a conversion from `D(U)` to `C(T)` should also exist.
     //! The precise requirements for being a `Constant` are embodied in the
     //! following laws.
     //!
     //!
     //! Minimal complete definition
     //! ---------------------------
     //! `value` and `to`, satisfying the laws below.
     //!
     //!
     //! Laws
     //! ----
     //! Let `c` be an object of with tag `C`, which represents a `Constant`
     //! holding an object with tag `T`. The first law ensures that the value
     //! of the wrapped object is always a constant expression by requiring
     //! the following to be well-formed:
     //! @code
     //!     constexpr auto x = hana::value<decltype(c)>();
     //! @endcode
     //!
     //! This means that the `value` function must return an object that can
     //! be constructed at compile-time. It is important to note how `value`
     //! only receives the type of the object and not the object itself.
     //! This is the core of the `Constant` concept; it means that the only
     //! information required to implement `value` must be stored in the _type_
     //! of its argument, and hence be available statically.
     //!
     //! The second law that must be satisfied ensures that `Constant`s are
     //! basically dumb boxes, which makes it possible to provide models for
     //! many concepts without much work from the user. The law simply asks
     //! for the following expression to be valid:
     //! @code
     //!     to<C>(i)
     //! @endcode
     //! where, `i` is an _arbitrary_ `Constant` holding an internal value
     //! with a tag that can be converted to `T`, as determined by the
     //! `hana::is_convertible` metafunction. In other words, whenever `U` is
     //! convertible to `T`, a `Constant` holding a `U` is convertible to
     //! a `Constant` holding a `T`, if such a `Constant` can be created.
     //!
     //! Finally, the tag `C` must provide a nested `value_type` alias to `T`,
     //! which allows us to query the tag of the inner value held by objects
     //! with tag `C`. In other words, the following must be true for any
     //! object `c` with tag `C`:
     //! @code
     //!     std::is_same<
     //!         C::value_type,
     //!         tag_of<decltype(hana::value(c))>::type
     //!     >::value
     //! @endcode
     //!
     //!
     //! Refined concepts
     //! ----------------
     //! In certain cases, a `Constant` can automatically be made a model of
     //! another concept. In particular, if a `Constant` `C` is holding an
     //! object of tag `T`, and if `T` models a concept `X`, then `C` may
     //! in most cases model `X` by simply performing whatever operation is
     //! required on its underlying value, and then wrapping the result back
     //! in a `C`.
     //!
     //! More specifically, if a `Constant` `C` has an underlying value
     //! (`C::value_type`) which is a model of `Comparable`, `Orderable`,
     //! `Logical`, or `Monoid` up to `EuclideanRing`, then `C` must also
     //! be a model of those concepts. In other words, when `C::value_type`
     //! models one of the listed concepts, `C` itself must also model that
     //! concept. However, note that free models are provided for all of
     //! those concepts, so no additional work must be done.
     //!
     //! While it would be possible in theory to provide models for concepts
     //! like `Foldable` too, only a couple of concepts are useful to have as
     //! `Constant` in practice. Providing free models for the concepts listed
     //! above is useful because it allows various types of integral constants
     //! (`std::integral_constant`, `mpl::integral_c`, etc...) to easily have
     //! models for them just by defining the `Constant` concept.
     //!
     //! @remark
     //! An interesting observation is that `Constant` is actually the
     //! canonical embedding of the subcategory of `constexpr` things
     //! into the Hana category, which contains everything in this library.
     //! Hence, whatever is true in that subcategory is also true here, via
     //! this functor. This is why we can provide models of any concept that
     //! works on `constexpr` things for Constants, by simply passing them
     //! through that embedding.
     //!
     //!
     //! Concrete models
     //! ---------------
     //! `hana::integral_constant`
     //!
     //!
     //! Provided conversion to the tag of the underlying value
     //! ------------------------------------------------------
     //! Any `Constant` `c` holding an underlying value of tag `T` is
     //! convertible to any tag `U` such that `T` is convertible to `U`.
     //! Specifically, the conversion is equivalent to
     //! @code
     //!     to<U>(c) == to<U>(value<decltype(c)>())
     //! @endcode
     //!
     //! Also, those conversions are marked as an embedding whenever the
     //! conversion of underlying types is an embedding. This is to allow
     //! Constants to inter-operate with `constexpr` objects easily:
     //! @code
     //!     plus(int_c<1>, 1) == 2
     //! @endcode
     //!
     //! Strictly speaking, __this is sometimes a violation__ of what it means
     //! to be an embedding. Indeed, while there exists an embedding from any
     //! Constant to a `constexpr` object (since Constant is just the canonical
     //! inclusion), there is no embedding from a Constant to a runtime
     //! object since we would lose the ability to define the `value` method
     //! (the `constexpr`ness of the object would have been lost). Since there
     //! is no way to distinguish `constexpr` and non-`constexpr` objects based
     //! on their type, Hana has no way to know whether the conversion is to a
     //! `constexpr` object of not. In other words, the `to` method has no way
     //! to differentiate between
     //! @code
     //!     constexpr int i = hana::to<int>(int_c<1>);
     //! @endcode
     //! which is an embedding, and
     //! @code
     //!     int i = hana::to<int>(int_c<1>);
     //! @endcode
     //!
     //! which isn't. To be on the safer side, we could mark the conversion
     //! as not-an-embedding. However, if e.g. the conversion from
     //! `integral_constant_tag<int>` to `int` was not marked as an embedding,
     //! we would have to write `plus(to<int>(int_c<1>), 1)` instead of just
     //! `plus(int_c<1>, 1)`, which is cumbersome. Hence, the conversion is
     //! marked as an embedding, but this also means that code like
     //! @code
     //!     int i = 1;
     //!     plus(int_c<1>, i);
     //! @endcode
     //! will be considered valid, which implicitly loses the fact that
     //! `int_c<1>` is a Constant, and hence does not follow the usual rules
     //! for cross-type operations in Hana.
     //!
     //!
     //! Provided common data type
     //! -------------------------
     //! Because of the requirement that `Constant`s be interchangeable when
     //! their contents are compatible, two `Constant`s `A` and `B` will have
     //! a common data type whenever `A::value_type` and `B::value_type` have
     //! one. Their common data type is an unspecified `Constant` `C` such
     //! that `C::value_type` is exactly `common_t<A::value_type, B::value_type>`.
     //! A specialization of the `common` metafunction is provided for
     //! `Constant`s to reflect this.
     //!
     //! In the same vein, a common data type is also provided from any
     //! constant `A` to a type `T` such that `A::value_type` and `T` share
     //! a common type. The common type between `A` and `T` is obviously the
     //! common type between `A::value_type` and `T`. As explained above in
     //! the section on conversions, this is sometimes a violation of the
     //! definition of a common type, because there must be an embedding
     //! to the common type, which is not always the case. For the same
     //! reasons as explained above, this common type is still provided.
     //!
     //!
     //! [1]: http://en.cppreference.com/w/cpp/named_req/LiteralType
     template <typename C>
     struct Constant;
 }} // end namespace boost::hana
 
 #endif // !BOOST_HANA_FWD_CONCEPT_CONSTANT_HPP

This page was automatically generated by the 2.3.7 LXR engine. The LXR team