hana/fwd/unfold_left.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::unfold_left`.
0004
0005 Copyright Louis Dionne 2013-2022
0006 Distributed under the Boost Software License, Version 1.0.
0007 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
0008  */
0009
0010 #ifndef BOOST_HANA_FWD_UNFOLD_LEFT_HPP
0011 #define BOOST_HANA_FWD_UNFOLD_LEFT_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! Dual operation to `fold_left` for sequences.
0019     //! @ingroup group-Sequence
0020     //!
0021     //! While `fold_left` reduces a structure to a summary value from the left,
0022     //! `unfold_left` builds a sequence from a seed value and a function,
0023     //! starting from the left.
0024     //!
0025     //!
0026     //! Signature
0027     //! ---------
0028     //! Given a `Sequence` `S`, an initial value `state` of tag `I`, an
0029     //! arbitrary Product `P` and a function \f$ f : I \to P(I, T) \f$,
0030     //! `unfold_left<S>` has the following signature:
0031     //! \f[
0032     //!     \mathtt{unfold\_left}_S : I \times (I \to P(I, T)) \to S(T)
0033     //! \f]
0034     //!
0035     //! @tparam S
0036     //! The tag of the sequence to build up.
0037     //!
0038     //! @param state
0039     //! An initial value to build the sequence from.
0040     //!
0041     //! @param f
0042     //! A function called as `f(state)`, where `state` is an initial value,
0043     //! and returning
0044     //! 1. `nothing` if it is done producing the sequence.
0045     //! 2. otherwise, `just(make<P>(state, x))`, where `state` is the new
0046     //!    initial value used in the next call to `f`, `x` is an element to
0047     //!    be appended to the resulting sequence, and `P` is an arbitrary
0048     //!    `Product`.
0049     //!
0050     //!
0051     //! Fun fact
0052     //! ---------
0053     //! In some cases, `unfold_left` can undo a `fold_left` operation:
0054     //! @code
0055     //!     unfold_left<S>(fold_left(xs, state, f), g) == xs
0056     //! @endcode
0057     //!
0058     //! if the following holds
0059     //! @code
0060     //!     g(f(x, y)) == just(make_pair(x, y))
0061     //!     g(state) == nothing
0062     //! @endcode
0063     //!
0064     //!
0065     //! Example
0066     //! -------
0067     //! @include example/unfold_left.cpp
0068 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0069     template <typename S>
0070     constexpr auto unfold_left = [](auto&& state, auto&& f) {
0071         return tag-dispatched;
0072     };
0073 #else
0074     template <typename S, typename = void>
0075     struct unfold_left_impl : unfold_left_impl<S, when<true>> { };
0076
0077     template <typename S>
0078     struct unfold_left_t;
0079
0080     template <typename S>
0081     BOOST_HANA_INLINE_VARIABLE constexpr unfold_left_t<S> unfold_left{};
0082 #endif
0083 }} // end namespace boost::hana
0084
0085 #endif // !BOOST_HANA_FWD_UNFOLD_LEFT_HPP