boost/hana/fwd/suffix.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::suffix`.
   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_SUFFIX_HPP
  11 #define BOOST_HANA_FWD_SUFFIX_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/core/when.hpp>
  15
  16
  17 BOOST_HANA_NAMESPACE_BEGIN
  18     //! Inserts a value after each element of a monadic structure.
  19     //! @ingroup group-MonadPlus
  20     //!
  21     //! Given a monadic structure `xs` and a value `z` (called the suffix),
  22     //! `suffix` returns a new monadic structure such that
  23     //! @code
  24     //!     suffix(xs, z) == flatten(transform(xs, [](auto x) {
  25     //!         return concat(lift<M>(x), lift<M>(z));
  26     //!     }))
  27     //! @endcode
  28     //!
  29     //! For sequences, this simply corresponds to inserting the suffix after
  30     //! each element of the sequence. For example, given a sequence
  31     //! `[x1, ..., xn]`, `suffix` will return
  32     //! @code
  33     //!     [x1, z, x2, z, ..., xn, z]
  34     //! @endcode
  35     //! As explained above, this can be generalized to other MonadPlus models,
  36     //! with various levels of interest.
  37     //!
  38     //!
  39     //! Signature
  40     //! ---------
  41     //! Given a MonadPlus `M`, the signature is
  42     //! @f$ \mathtt{suffix} : M(T) \times T \to M(T) @f$.
  43     //!
  44     //! @param xs
  45     //! A monadic structure.
  46     //!
  47     //! @param sfx
  48     //! A value (the suffix) to insert after each element of a monadic
  49     //! structure.
  50     //!
  51     //!
  52     //! Example
  53     //! -------
  54     //! @include example/suffix.cpp
  55 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  56     constexpr auto suffix = [](auto&& xs, auto&& sfx) {
  57         return tag-dispatched;
  58     };
  59 #else
  60     template <typename M, typename = void>
  61     struct suffix_impl : suffix_impl<M, when<true>> { };
  62
  63     struct suffix_t {
  64         template <typename Xs, typename Sfx>
  65         constexpr auto operator()(Xs&& xs, Sfx&& sfx) const;
  66     };
  67
  68     constexpr suffix_t suffix{};
  69 #endif
  70 BOOST_HANA_NAMESPACE_END
  71
  72 #endif // !BOOST_HANA_FWD_SUFFIX_HPP