boost/hana/fwd/cycle.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::cycle`.
   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_CYCLE_HPP
  11 #define BOOST_HANA_FWD_CYCLE_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/core/when.hpp>
  15
  16
  17 BOOST_HANA_NAMESPACE_BEGIN
  18     //! Combine a monadic structure with itself `n` times.
  19     //! @ingroup group-MonadPlus
  20     //!
  21     //! Given a monadic structure `xs` and a non-negative number `n`,
  22     //! `cycle` returns a new monadic structure which is the result of
  23     //! combining `xs` with itself `n` times using the `concat` operation.
  24     //! In other words,
  25     //! @code
  26     //!     cycle(xs, n) == concat(xs, concat(xs, ... concat(xs, xs)))
  27     //!                                       // ^^^^^ n times total
  28     //! @endcode
  29     //!
  30     //! Also note that since `concat` is required to be associative, we
  31     //! could also have written
  32     //! @code
  33     //!     cycle(xs, n) == concat(concat(... concat(xs, xs), xs), xs)
  34     //!                               // ^^^^^ n times total
  35     //! @endcode
  36     //!
  37     //! If `n` is zero, then the identity of `concat`, `empty`, is returned.
  38     //! In the case of sequences, this boils down to returning a sequence
  39     //! containing `n` copies of itself; for other models it might differ.
  40     //!
  41     //!
  42     //! Signature
  43     //! ---------
  44     //! Given an `IntegralConstant` `C` and a `MonadPlus` `M`, the signature is
  45     //! @f$ \mathrm{cycle} : M(T) \times C \to M(T) @f$.
  46     //!
  47     //! @param xs
  48     //! A monadic structure to combine with itself a certain number of times.
  49     //!
  50     //! @param n
  51     //! A non-negative `IntegralConstant` representing the number of times to
  52     //! combine the monadic structure with itself. If `n` is zero, `cycle`
  53     //! returns `empty`.
  54     //!
  55     //!
  56     //! Example
  57     //! -------
  58     //! @include example/cycle.cpp
  59 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  60     constexpr auto cycle = [](auto&& xs, auto const& n) {
  61         return tag-dispatched;
  62     };
  63 #else
  64     template <typename M, typename = void>
  65     struct cycle_impl : cycle_impl<M, when<true>> { };
  66
  67     struct cycle_t {
  68         template <typename Xs, typename N>
  69         constexpr auto operator()(Xs&& xs, N const& n) const;
  70     };
  71
  72     constexpr cycle_t cycle{};
  73 #endif
  74 BOOST_HANA_NAMESPACE_END
  75
  76 #endif // !BOOST_HANA_FWD_CYCLE_HPP