boost/hana/fwd/append.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::append`.
   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_APPEND_HPP
  11 #define BOOST_HANA_FWD_APPEND_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/core/when.hpp>
  15
  16
  17 BOOST_HANA_NAMESPACE_BEGIN
  18     //! Append an element to a monadic structure.
  19     //! @ingroup group-MonadPlus
  20     //!
  21     //! Given an element `x` and a monadic structure `xs`, `append` returns a
  22     //! new monadic structure which is the result of lifting `x` into the
  23     //! monadic structure and then combining that (to the right) with `xs`.
  24     //! In other words,
  25     //! @code
  26     //!     append(xs, x) == concat(xs, lift<Xs>(x))
  27     //! @endcode
  28     //! where `Xs` is the tag of `xs`. For sequences, this has the intuitive
  29     //! behavior of simply appending an element to the end of the sequence,
  30     //! hence the name.
  31     //!
  32     //! > #### Rationale for not calling this `push_back`
  33     //! > See the rationale for using `prepend` instead of `push_front`.
  34     //!
  35     //!
  36     //! Signature
  37     //! ---------
  38     //! Given a MonadPlus `M`, the signature is
  39     //! @f$ \mathtt{append} : M(T) \times T \to M(T) @f$.
  40     //!
  41     //! @param xs
  42     //! A monadic structure that will be combined to the left of the element.
  43     //!
  44     //! @param x
  45     //! An element to combine to the right of the monadic structure.
  46     //!
  47     //!
  48     //! Example
  49     //! -------
  50     //! @include example/append.cpp
  51 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  52     constexpr auto append = [](auto&& xs, auto&& x) {
  53         return tag-dispatched;
  54     };
  55 #else
  56     template <typename M, typename = void>
  57     struct append_impl : append_impl<M, when<true>> { };
  58
  59     struct append_t {
  60         template <typename Xs, typename X>
  61         constexpr auto operator()(Xs&& xs, X&& x) const;
  62     };
  63
  64     constexpr append_t append{};
  65 #endif
  66 BOOST_HANA_NAMESPACE_END
  67
  68 #endif // !BOOST_HANA_FWD_APPEND_HPP