hana/fwd/scan_left.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::scan_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_SCAN_LEFT_HPP
0011 #define BOOST_HANA_FWD_SCAN_LEFT_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 left and return a list containing the
0019     //! successive reduction states.
0020     //! @ingroup group-Sequence
0021     //!
0022     //! Like `fold_left`, `scan_left` reduces a sequence to a single value
0023     //! using a binary operation. However, unlike `fold_left`, 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_left`, `scan_left` 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_left`, using `scan_left`
0033     //! on an empty sequence without an initial state is not an error.
0034     //!
0035     //! More specifically, `scan_left([x1, ..., xn], state, f)` is a sequence
0036     //! whose `i`th element is equivalent to `fold_left([x1, ..., xi], state, f)`.
0037     //! The no-state variant is handled in an analogous way. For illustration,
0038     //! consider this left fold on a short sequence:
0039     //! @code
0040     //!     fold_left([x1, x2, x3], state, f) == f(f(f(state, x1), x2), x3)
0041     //! @endcode
0042     //!
0043     //! The analogous sequence generated with `scan_left` will be
0044     //! @code
0045     //!     scan_left([x1, x2, x3], state, f) == [
0046     //!         state,
0047     //!         f(state, x1),
0048     //!         f(f(state, x1), x2),
0049     //!         f(f(f(state, x1), x2), x3)
0050     //!     ]
0051     //! @endcode
0052     //!
0053     //! Similarly, consider this left fold (without an initial state) on
0054     //! a short sequence:
0055     //! @code
0056     //!     fold_left([x1, x2, x3, x4], f) == f(f(f(x1, x2), x3), x4)
0057     //! @endcode
0058     //!
0059     //! The analogous sequence generated with `scan_left` will be
0060     //! @code
0061     //!     scan_left([x1, x2, x3, x4], f) == [
0062     //!         x1,
0063     //!         f(x1, x2),
0064     //!         f(f(x1, x2), x3),
0065     //!         f(f(f(x1, x2), x3), x4)
0066     //!     ]
0067     //! @endcode
0068     //!
0069     //! @param xs
0070     //! The sequence to scan from the left.
0071     //!
0072     //! @param state
0073     //! The (optional) initial reduction state.
0074     //!
0075     //! @param f
0076     //! A binary function called as `f(state, x)`, where `state` is the
0077     //! result accumulated so far and `x` is an element in the sequence.
0078     //! If no initial state is provided, `f` is called as `f(x1, x2)`,
0079     //! where `x1` and `x2` are both elements of the sequence.
0080     //!
0081     //!
0082     //! Example
0083     //! -------
0084     //! @include example/scan_left.cpp
0085 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0086     constexpr auto scan_left = [](auto&& xs[, auto&& state], auto const& f) {
0087         return tag-dispatched;
0088     };
0089 #else
0090     template <typename S, typename = void>
0091     struct scan_left_impl : scan_left_impl<S, when<true>> { };
0092
0093     struct scan_left_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_left_t scan_left{};
0102 #endif
0103 }} // end namespace boost::hana
0104
0105 #endif // !BOOST_HANA_FWD_SCAN_LEFT_HPP