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

Warning, file /include/boost/hana/fwd/core/to.hpp was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

 /*!
 @file
 Forward declares `boost::hana::to` and related utilities.
 
 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_CORE_TO_HPP
 #define BOOST_HANA_FWD_CORE_TO_HPP
 
 #include <boost/hana/config.hpp>
 
 
 namespace boost { namespace hana {
     //! @ingroup group-core
     //! Converts an object from one data type to another.
     //!
     //! `to` is a natural extension of the `static_cast` language construct to
     //! data types. Given a destination data type `To` and an object `x`, `to`
     //! creates a new object of data type `To` from `x`. Note, however, that
     //! `to` is not required to actually create a new object, and may return a
     //! reference to the original object (for example when trying to convert
     //! an object to its own data type).
     //!
     //! As a natural extension to `static_cast`, `to` provides a default
     //! behavior. For the purpose of what follows, let `To` be the destination
     //! data type and `From` be the data type of `x`, i.e. the source data type.
     //! Then, `to` has the following default behavior:
     //! 1. If the `To` and `From` data types are the same, then the object
     //!    is forwarded as-is.
     //! 2. Otherwise, if `From` is convertible to `To` using `static_cast`,
     //!    `x` is converted to `From` using `static_cast`.
     //! 3. Otherwise, calling `to<From>(x)` triggers a static assertion.
     //!
     //! However, `to` is a tag-dispatched function, which means that `to_impl`
     //! may be specialized in the `boost::hana` namespace to customize its
     //! behavior for arbitrary data types. Also note that `to` is tag-dispatched
     //! using both the `To` and the `From` data types, which means that `to_impl`
     //! is called as `to_impl<To, From>::%apply(x)`. Also note that some
     //! concepts provide conversions to or from their models. For example,
     //! any `Foldable` may be converted into a `Sequence`. This is achieved
     //! by specializing `to_impl<To, From>` whenever `To` is a `Sequence` and
     //! `From` is a `Foldable`. When such conversions are provided, they are
     //! documented in the source concept, in this case `Foldable`.
     //!
     //!
     //! Hana-convertibility
     //! -------------------
     //! When an object `x` of data type `From` can be converted to a data type
     //! `To` using `to`, we say that `x` is Hana-convertible to the data type
     //! `To`. We also say that there is a Hana-conversion from `From` to `To`.
     //! This bit of terminology is useful to avoid mistaking the various kinds
     //! of conversions C++ offers.
     //!
     //!
     //! Embeddings
     //! ----------
     //! As you might have seen by now, Hana uses algebraic and category-
     //! theoretical structures all around the place to help specify concepts
     //! in a rigorous way. These structures always have operations associated
     //! to them, which is why they are useful. The notion of embedding captures
     //! the idea of injecting a smaller structure into a larger one while
     //! preserving the operations of the structure. In other words, an
     //! embedding is an injective mapping that is also structure-preserving.
     //! Exactly what it means for a structure's operations to be preserved is
     //! left to explain by the documentation of each structure. For example,
     //! when we talk of a Monoid-embedding from a Monoid `A` to a Monoid `B`,
     //! we simply mean an injective transformation that preserves the identity
     //! and the associative operation, as documented in `Monoid`.
     //!
     //! But what does this have to do with the `to` function? Quite simply,
     //! the `to` function is a mapping between two data types, which will
     //! sometimes be some kind of structure, and it is sometimes useful to
     //! know whether such a mapping is well-behaved, i.e. lossless and
     //! structure preserving. The criterion for this conversion to be well-
     //! behaved is exactly that of being an embedding. To specify that a
     //! conversion is an embedding, simply use the `embedding` type as a
     //! base class of the corresponding `to_impl` specialization. Obviously,
     //! you should make sure the conversion is really an embedding, unless
     //! you want to shoot yourself in the foot.
     //!
     //!
     //! @tparam To
     //! The data type to which `x` should be converted.
     //!
     //! @param x
     //! The object to convert to the given data type.
     //!
     //!
     //! Example
     //! -------
     //! @include example/core/convert/to.cpp
 #ifdef BOOST_HANA_DOXYGEN_INVOKED
     template <typename To>
     constexpr auto to = [](auto&& x) -> decltype(auto) {
         return tag-dispatched;
     };
 #else
     template <typename To, typename From, typename = void>
     struct to_impl;
 
     template <typename To>
     struct to_t {
         template <typename X>
         constexpr decltype(auto) operator()(X&& x) const;
     };
 
     template <typename To>
     BOOST_HANA_INLINE_VARIABLE constexpr to_t<To> to{};
 #endif
 
     //! @ingroup group-core
     //! Returns whether there is a Hana-conversion from a data type to another.
     //!
     //! Specifically, `is_convertible<From, To>` is whether calling `to<To>`
     //! with an object of data type `From` would _not_ trigger a static
     //! assertion.
     //!
     //!
     //! Example
     //! -------
     //! @include example/core/convert/is_convertible.cpp
 #ifdef BOOST_HANA_DOXYGEN_INVOKED
     template <typename From, typename To>
     struct is_convertible { see documentation };
 #else
     template <typename From, typename To, typename = void>
     struct is_convertible;
 #endif
 
     //! @ingroup group-core
     //! Marks a conversion between data types as being an embedding.
     //!
     //! To mark a conversion between two data types `To` and `From` as
     //! an embedding, simply use `embedding<true>` (or simply `embedding<>`)
     //! as a base class of the corresponding `to_impl` specialization.
     //! If a `to_impl` specialization does not inherit `embedding<true>`
     //! or `embedding<>`, then it is not considered an embedding by the
     //! `is_embedded` metafunction.
     //!
     //! > #### Tip
     //! > The boolean template parameter is useful for marking a conversion
     //! > as an embedding only when some condition is satisfied.
     //!
     //!
     //! Example
     //! -------
     //! @include example/core/convert/embedding.cpp
     template <bool = true>
     struct embedding { };
 
     //! @ingroup group-core
     //! Returns whether a data type can be embedded into another data type.
     //!
     //! Given two data types `To` and `From`, `is_embedded<From, To>` returns
     //! whether `From` is convertible to `To`, and whether that conversion is
     //! also an embedding, as signaled by the `embedding` type.
     //!
     //!
     //! Example
     //! -------
     //! @include example/core/convert/is_embedded.cpp
 #ifdef BOOST_HANA_DOXYGEN_INVOKED
     template <typename From, typename To>
     struct is_embedded { see documentation };
 #else
     template <typename From, typename To, typename = void>
     struct is_embedded;
 #endif
 }} // end namespace boost::hana
 
 #endif // !BOOST_HANA_FWD_CORE_TO_HPP

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