1 /*! 2 @file 3 Forward declares `boost::hana::prepend`. 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_PREPEND_HPP 11 #define BOOST_HANA_FWD_PREPEND_HPP 12 13 #include <boost/hana/config.hpp> 14 #include <boost/hana/core/when.hpp> 15 16 17 BOOST_HANA_NAMESPACE_BEGIN 18 //! Prepend an element to a monadic structure. 19 //! @ingroup group-MonadPlus 20 //! 21 //! Given a monadic structure `xs` and an element `x`, `prepend` returns 22 //! a new monadic structure which is the result of lifting `x` into the 23 //! monadic structure and then combining that (to the left) with `xs`. 24 //! In other words, 25 //! @code 26 //! prepend(xs, x) == concat(lift<Xs>(x), xs) 27 //! @endcode 28 //! 29 //! For sequences, this has the intuitive behavior of simply prepending 30 //! an element to the beginning of the sequence, hence the name. 31 //! 32 //! > #### Rationale for not calling this `push_front` 33 //! > While `push_front` is the de-facto name used in the standard library, 34 //! > it also strongly suggests mutation of the underlying sequence, which 35 //! > is not the case here. The author also finds that `push_front` 36 //! > suggests too strongly the sole interpretation of putting an 37 //! > element to the front of a sequence, whereas `prepend` is slightly 38 //! > more nuanced and bears its name better for e.g. `hana::optional`. 39 //! 40 //! 41 //! Signature 42 //! --------- 43 //! Given a MonadPlus `M`, the signature is 44 //! @f$ \mathtt{prepend} : M(T) \times T \to M(T) @f$. 45 //! 46 //! @param xs 47 //! A monadic structure that will be combined to the right of the element. 48 //! 49 //! @param x 50 //! An element to combine to the left of the monadic structure. 51 //! 52 //! 53 //! Example 54 //! ------- 55 //! @include example/prepend.cpp 56 #ifdef BOOST_HANA_DOXYGEN_INVOKED __anon0c1940690102(auto&& xs, auto&& x) 57 constexpr auto prepend = [](auto&& xs, auto&& x) { 58 return tag-dispatched; 59 }; 60 #else 61 template <typename M, typename = void> 62 struct prepend_impl : prepend_impl<M, when<true>> { }; 63 64 struct prepend_t { 65 template <typename Xs, typename X> 66 constexpr auto operator()(Xs&& xs, X&& x) const; 67 }; 68 69 constexpr prepend_t prepend{}; 70 #endif 71 BOOST_HANA_NAMESPACE_END 72 73 #endif // !BOOST_HANA_FWD_PREPEND_HPP 74