hana/fwd/tap.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::tap`.
0004
0005 Copyright Louis Dionne 2013-2022
0006 Distributed under the Boost Software License, Version 1.0.
0007 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
0008  */
0009
0010 #ifndef BOOST_HANA_FWD_TAP_HPP
0011 #define BOOST_HANA_FWD_TAP_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! Tap inside a monadic chain.
0019     //! @ingroup group-Monad
0020     //!
0021     //! Given a function `f`, `tap<M>` returns a new function which performs
0022     //! `f` on its argument and then returns the argument lifted in the `M`
0023     //! `Monad`. Combined with the property that `chain(m, lift<M>) == m`,
0024     //! this provides a way of executing an action inside a monadic chain
0025     //! without influencing its overall result. This is useful to e.g. insert
0026     //! debug statements or perform actions that are not tied to the chain but
0027     //! that need to be executed inside of it.
0028     //!
0029     //! @note
0030     //! Since C++ is not a pure language, it is possible to perform side
0031     //! effects inside the `f` function. Actually, side effects are the
0032     //! only reason why one might want to use `tap`. However, one should
0033     //! not rely on the side effects being done in any specific order.
0034     //!
0035     //!
0036     //! @tparam M
0037     //! The tag (a `Monad`) of the monads in the tapped monadic chain.
0038     //!
0039     //! @param f
0040     //! A function to be executed inside a monadic chain. It will be called
0041     //! as `f(x)`, where `x` is a value inside the previous monad in the
0042     //! chain. The result of `f` is always discarded.
0043     //!
0044     //!
0045     //! Example
0046     //! -------
0047     //! @include example/tap.cpp
0048 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0049     template <typename M>
0050     constexpr auto tap = [](auto&& f) {
0051         return tag-dispatched;
0052     };
0053 #else
0054     template <typename M, typename = void>
0055     struct tap_impl : tap_impl<M, when<true>> { };
0056
0057     template <typename M>
0058     struct tap_t {
0059         template <typename F>
0060         constexpr auto operator()(F&& f) const;
0061     };
0062
0063     template <typename M>
0064     BOOST_HANA_INLINE_VARIABLE constexpr tap_t<M> tap{};
0065 #endif
0066 }} // end namespace boost::hana
0067
0068 #endif // !BOOST_HANA_FWD_TAP_HPP