hana/fwd/ap.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::ap`.
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_AP_HPP
0011 #define BOOST_HANA_FWD_AP_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! Lifted application.
0019     //! @ingroup group-Applicative
0020     //!
0021     //! Specifically, `ap` applies a structure containing functions to a
0022     //! structure containing values, and returns a new structure containing
0023     //! values. The exact way in which the functions are applied to the values
0024     //! depends on the `Applicative`.
0025     //!
0026     //! `ap` can be called with two arguments or more; the functions in the `f`
0027     //! structure are curried and then applied to the values in each `x...`
0028     //! structure using the binary form of `ap`. Note that this requires the
0029     //! number of `x...` must match the arity of the functions in the `f`
0030     //! structure. In other words, `ap(f, x1, ..., xN)` is equivalent to
0031     //! @code
0032     //!     ((curry(f) ap x1) ap x2) ... ap xN
0033     //! @endcode
0034     //! where `x ap y` is just `ap(x, y)` written in infix notation to
0035     //! emphasize the left associativity.
0036     //!
0037     //!
0038     //! Signature
0039     //! ---------
0040     //! Given an Applicative `A`, the signature is
0041     //! @f$ \mathtt{ap} : A(T_1 \times \cdots \times T_n \to U)
0042     //!                   \times A(T_1) \times \cdots \times A(T_n)
0043     //!                   \to A(U) @f$.
0044     //!
0045     //! @param f
0046     //! A structure containing function(s).
0047     //!
0048     //! @param x...
0049     //! Structure(s) containing value(s) and on which `f` is applied. The
0050     //! number of structures must match the arity of the functions in the
0051     //! `f` structure.
0052     //!
0053     //!
0054     //! Example
0055     //! -------
0056     //! @include example/ap.cpp
0057     //!
0058     //! @todo
0059     //! Consider giving access to all the arguments to the tag-dispatched
0060     //! implementation for performance purposes.
0061 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0062     constexpr auto ap = [](auto&& f, auto&& ...x) -> decltype(auto) {
0063         return tag-dispatched;
0064     };
0065 #else
0066     template <typename A, typename = void>
0067     struct ap_impl : ap_impl<A, when<true>> { };
0068
0069     struct ap_t {
0070         template <typename F, typename X>
0071         constexpr decltype(auto) operator()(F&& f, X&& x) const;
0072
0073         template <typename F, typename ...Xs>
0074         constexpr decltype(auto) operator()(F&& f, Xs&& ...xs) const;
0075     };
0076
0077     BOOST_HANA_INLINE_VARIABLE constexpr ap_t ap{};
0078 #endif
0079 }} // end namespace boost::hana
0080
0081 #endif // !BOOST_HANA_FWD_AP_HPP