hana/fwd/scan_right.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::scan_right`.
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_SCAN_RIGHT_HPP
0011 #define BOOST_HANA_FWD_SCAN_RIGHT_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! Fold a Sequence to the right and return a list containing the
0019     //! successive reduction states.
0020     //! @ingroup group-Sequence
0021     //!
0022     //! Like `fold_right`, `scan_right` reduces a sequence to a single value
0023     //! using a binary operation. However, unlike `fold_right`, it builds up
0024     //! a sequence of the intermediary results computed along the way and
0025     //! returns that instead of only the final reduction state. Like
0026     //! `fold_right`, `scan_right` can be used with or without an initial
0027     //! reduction state.
0028     //!
0029     //! When the sequence is empty, two things may arise. If an initial state
0030     //! was provided, a singleton list containing that state is returned.
0031     //! Otherwise, if no initial state was provided, an empty list is
0032     //! returned. In particular, unlike for `fold_right`, using `scan_right`
0033     //! on an empty sequence without an initial state is not an error.
0034     //!
0035     //! More specifically, `scan_right([x1, ..., xn], state, f)` is a sequence
0036     //! whose `i`th element is equivalent to `fold_right([x1, ..., xi], state, f)`.
0037     //! The no-state variant is handled in an analogous way. For illustration,
0038     //! consider this right fold on a short sequence:
0039     //! @code
0040     //!     fold_right([x1, x2, x3], state, f) == f(x1, f(x2, f(x3, state)))
0041     //! @endcode
0042     //!
0043     //! The analogous sequence generated with `scan_right` will be
0044     //! @code
0045     //!     scan_right([x1, x2, x3], state, f) == [
0046     //!         f(x1, f(x2, f(x3, state))),
0047     //!               f(x2, f(x3, state)),
0048     //!                     f(x3, state),
0049     //!                           state
0050     //!     ]
0051     //! @endcode
0052     //!
0053     //! Similarly, consider this right fold (without an initial state) on
0054     //! a short sequence:
0055     //! @code
0056     //!     fold_right([x1, x2, x3, x4], f) == f(x1, f(x2, f(x3, x4)))
0057     //! @endcode
0058     //!
0059     //! The analogous sequence generated with `scan_right` will be
0060     //! @code
0061     //!     scan_right([x1, x2, x3, x4], f) == [
0062     //!         f(x1, f(x2, f(x3, x4))),
0063     //!               f(x2, f(x3, x4)),
0064     //!                     f(x3, x4),
0065     //!                           x4
0066     //!     ]
0067     //! @endcode
0068     //!
0069     //! @param xs
0070     //! The sequence to scan from the right.
0071     //!
0072     //! @param state
0073     //! The (optional) initial reduction state.
0074     //!
0075     //! @param f
0076     //! A binary function called as `f(x, state)`, where `state` is the
0077     //! result accumulated so far and `x` is an element in the sequence.
0078     //! When no initial state is provided, `f` is called as `f(x1, x2)`,
0079     //! where `x1` and `x2` are elements of the sequence.
0080     //!
0081     //!
0082     //! Example
0083     //! -------
0084     //! @include example/scan_right.cpp
0085 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0086     constexpr auto scan_right = [](auto&& xs[, auto&& state], auto const& f) {
0087         return tag-dispatched;
0088     };
0089 #else
0090     template <typename S, typename = void>
0091     struct scan_right_impl : scan_right_impl<S, when<true>> { };
0092
0093     struct scan_right_t {
0094         template <typename Xs, typename State, typename F>
0095         constexpr auto operator()(Xs&& xs, State&& state, F const& f) const;
0096
0097         template <typename Xs, typename F>
0098         constexpr auto operator()(Xs&& xs, F const& f) const;
0099     };
0100
0101     BOOST_HANA_INLINE_VARIABLE constexpr scan_right_t scan_right{};
0102 #endif
0103 }} // end namespace boost::hana
0104
0105 #endif // !BOOST_HANA_FWD_SCAN_RIGHT_HPP