1 /*! 2 @file 3 Forward declares `boost::hana::filter`. 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_FILTER_HPP 11 #define BOOST_HANA_FWD_FILTER_HPP 12 13 #include <boost/hana/config.hpp> 14 #include <boost/hana/core/when.hpp> 15 16 17 BOOST_HANA_NAMESPACE_BEGIN 18 //! Filter a monadic structure using a custom predicate. 19 //! @ingroup group-MonadPlus 20 //! 21 //! Given a monadic structure and a predicate, `filter` returns a new 22 //! monadic structure containing only those elements that satisfy the 23 //! predicate. This is a generalization of the usual `filter` function 24 //! for sequences; it works for any MonadPlus. Intuitively, `filter` is 25 //! somewhat equivalent to: 26 //! @code 27 //! filter(xs, pred) == flatten(transform(xs, [](auto x) { 28 //! return pred(x) ? lift<Xs>(x) : empty<Xs>(); 29 //! }) 30 //! @endcode 31 //! In other words, we basically turn a monadic structure containing 32 //! `[x1, ..., xn]` into a monadic structure containing 33 //! @code 34 //! [ 35 //! pred(x1) ? [x1] : [], 36 //! pred(x2) ? [x2] : [], 37 //! ... 38 //! pred(xn) ? [xn] : [] 39 //! ] 40 //! @endcode 41 //! and we then `flatten` that. 42 //! 43 //! 44 //! Signature 45 //! --------- 46 //! Given a `MonadPlus` `M` and an `IntegralConstant` `Bool` holding a 47 //! value of type `bool`, the signature is 48 //! @f$ \mathtt{filter} : M(T) \times (T \to \mathtt{Bool}) \to M(T) @f$. 49 //! 50 //! @param xs 51 //! The monadic structure to filter. 52 //! 53 //! @param pred 54 //! A function called as `pred(x)` for each element `x` in the monadic 55 //! structure and returning whether that element should be __kept__ in 56 //! the resulting structure. In the current version of the library, the 57 //! predicate has to return an `IntegralConstant` holding a value 58 //! convertible to a `bool`. 59 //! 60 //! 61 //! Example 62 //! ------- 63 //! @include example/filter.cpp 64 #ifdef BOOST_HANA_DOXYGEN_INVOKED __anonae7253980102(auto&& xs, auto&& pred) 65 constexpr auto filter = [](auto&& xs, auto&& pred) { 66 return tag-dispatched; 67 }; 68 #else 69 template <typename M, typename = void> 70 struct filter_impl : filter_impl<M, when<true>> { }; 71 72 struct filter_t { 73 template <typename Xs, typename Pred> 74 constexpr auto operator()(Xs&& xs, Pred&& pred) const; 75 }; 76 77 constexpr filter_t filter{}; 78 #endif 79 BOOST_HANA_NAMESPACE_END 80 81 #endif // !BOOST_HANA_FWD_FILTER_HPP 82