boost/hana/fwd/tap.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::tap`.
   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_TAP_HPP
  11 #define BOOST_HANA_FWD_TAP_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/core/when.hpp>
  15
  16
  17 BOOST_HANA_NAMESPACE_BEGIN
  18     //! Tap inside a monadic chain.
  19     //! @ingroup group-Monad
  20     //!
  21     //! Given a function `f`, `tap<M>` returns a new function which performs
  22     //! `f` on its argument and then returns the argument lifted in the `M`
  23     //! `Monad`. Combined with the property that `chain(m, lift<M>) == m`,
  24     //! this provides a way of executing an action inside a monadic chain
  25     //! without influencing its overall result. This is useful to e.g. insert
  26     //! debug statements or perform actions that are not tied to the chain but
  27     //! that need to be executed inside of it.
  28     //!
  29     //! @note
  30     //! Since C++ is not a pure language, it is possible to perform side
  31     //! effects inside the `f` function. Actually, side effects are the
  32     //! only reason why one might want to use `tap`. However, one should
  33     //! not rely on the side effects being done in any specific order.
  34     //!
  35     //!
  36     //! @tparam M
  37     //! The tag (a `Monad`) of the monads in the tapped monadic chain.
  38     //!
  39     //! @param f
  40     //! A function to be executed inside a monadic chain. It will be called
  41     //! as `f(x)`, where `x` is a value inside the previous monad in the
  42     //! chain. The result of `f` is always discarded.
  43     //!
  44     //!
  45     //! Example
  46     //! -------
  47     //! @include example/tap.cpp
  48 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  49     template <typename M>
  50     constexpr auto tap = [](auto&& f) {
  51         return tag-dispatched;
  52     };
  53 #else
  54     template <typename M, typename = void>
  55     struct tap_impl : tap_impl<M, when<true>> { };
  56
  57     template <typename M>
  58     struct tap_t;
  59
  60     template <typename M>
  61     constexpr tap_t<M> tap{};
  62 #endif
  63 BOOST_HANA_NAMESPACE_END
  64
  65 #endif // !BOOST_HANA_FWD_TAP_HPP