]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*! |
2 | @file | |
3 | Forward declares `boost::hana::scan_right`. | |
4 | ||
5 | @copyright Louis Dionne 2013-2016 | |
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_SCAN_RIGHT_HPP | |
11 | #define BOOST_HANA_FWD_SCAN_RIGHT_HPP | |
12 | ||
13 | #include <boost/hana/config.hpp> | |
14 | #include <boost/hana/core/when.hpp> | |
15 | ||
16 | ||
17 | BOOST_HANA_NAMESPACE_BEGIN | |
18 | //! Fold a Sequence to the right and return a list containing the | |
19 | //! successive reduction states. | |
20 | //! @ingroup group-Sequence | |
21 | //! | |
22 | //! Like `fold_right`, `scan_right` reduces a sequence to a single value | |
23 | //! using a binary operation. However, unlike `fold_right`, it builds up | |
24 | //! a sequence of the intermediary results computed along the way and | |
25 | //! returns that instead of only the final reduction state. Like | |
26 | //! `fold_right`, `scan_right` can be used with or without an initial | |
27 | //! reduction state. | |
28 | //! | |
29 | //! When the sequence is empty, two things may arise. If an initial state | |
30 | //! was provided, a singleton list containing that state is returned. | |
31 | //! Otherwise, if no initial state was provided, an empty list is | |
32 | //! returned. In particular, unlike for `fold_right`, using `scan_right` | |
33 | //! on an empty sequence without an initial state is not an error. | |
34 | //! | |
35 | //! More specifically, `scan_right([x1, ..., xn], state, f)` is a sequence | |
36 | //! whose `i`th element is equivalent to `fold_right([x1, ..., xi], state, f)`. | |
37 | //! The no-state variant is handled in an analogous way. For illustration, | |
38 | //! consider this right fold on a short sequence: | |
39 | //! @code | |
40 | //! fold_right([x1, x2, x3], state, f) == f(x1, f(x2, f(x3, state))) | |
41 | //! @endcode | |
42 | //! | |
43 | //! The analogous sequence generated with `scan_right` will be | |
44 | //! @code | |
45 | //! scan_right([x1, x2, x3], state, f) == [ | |
46 | //! f(x1, f(x2, f(x3, state))), | |
47 | //! f(x2, f(x3, state)), | |
48 | //! f(x3, state), | |
49 | //! state | |
50 | //! ] | |
51 | //! @endcode | |
52 | //! | |
53 | //! Similarly, consider this right fold (without an initial state) on | |
54 | //! a short sequence: | |
55 | //! @code | |
56 | //! fold_right([x1, x2, x3, x4], f) == f(x1, f(x2, f(x3, x4))) | |
57 | //! @endcode | |
58 | //! | |
59 | //! The analogous sequence generated with `scan_right` will be | |
60 | //! @code | |
61 | //! scan_right([x1, x2, x3, x4], f) == [ | |
62 | //! f(x1, f(x2, f(x3, x4))), | |
63 | //! f(x2, f(x3, x4)), | |
64 | //! f(x3, x4), | |
65 | //! x4 | |
66 | //! ] | |
67 | //! @endcode | |
68 | //! | |
69 | //! @param xs | |
70 | //! The sequence to scan from the right. | |
71 | //! | |
72 | //! @param state | |
73 | //! The (optional) initial reduction state. | |
74 | //! | |
75 | //! @param f | |
76 | //! A binary function called as `f(x, state)`, where `state` is the | |
77 | //! result accumulated so far and `x` is an element in the sequence. | |
78 | //! When no initial state is provided, `f` is called as `f(x1, x2)`, | |
79 | //! where `x1` and `x2` are elements of the sequence. | |
80 | //! | |
81 | //! | |
82 | //! Example | |
83 | //! ------- | |
84 | //! @include example/scan_right.cpp | |
85 | #ifdef BOOST_HANA_DOXYGEN_INVOKED | |
86 | constexpr auto scan_right = [](auto&& xs[, auto&& state], auto const& f) { | |
87 | return tag-dispatched; | |
88 | }; | |
89 | #else | |
90 | template <typename S, typename = void> | |
91 | struct scan_right_impl : scan_right_impl<S, when<true>> { }; | |
92 | ||
93 | struct scan_right_t { | |
94 | template <typename Xs, typename State, typename F> | |
95 | constexpr auto operator()(Xs&& xs, State&& state, F const& f) const; | |
96 | ||
97 | template <typename Xs, typename F> | |
98 | constexpr auto operator()(Xs&& xs, F const& f) const; | |
99 | }; | |
100 | ||
101 | constexpr scan_right_t scan_right{}; | |
102 | #endif | |
103 | BOOST_HANA_NAMESPACE_END | |
104 | ||
105 | #endif // !BOOST_HANA_FWD_SCAN_RIGHT_HPP |