hana/fwd/fold_right.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::fold_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_FOLD_RIGHT_HPP
0011 #define BOOST_HANA_FWD_FOLD_RIGHT_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! Right-fold of a structure using a binary operation and an optional
0019     //! initial reduction state.
0020     //! @ingroup group-Foldable
0021     //!
0022     //! `fold_right` is a right-associative fold using a binary operation.
0023     //! Given a structure containing `x1, ..., xn`, a function `f` and
0024     //! an optional initial state, `fold_right` applies `f` as follows
0025     //! @code
0026     //!     f(x1, f(x2, f(x3, f(x4, ... f(xn-1, xn) ... )))) // without state
0027     //!     f(x1, f(x2, f(x3, f(x4, ... f(xn, state) ... )))) // with state
0028     //! @endcode
0029     //!
0030     //! @note
0031     //! It is worth noting that the order in which the binary function should
0032     //! expect its arguments is reversed from `fold_left`.
0033     //!
0034     //! When the structure is empty, two things may arise. If an initial
0035     //! state was provided, it is returned as-is. Otherwise, if the no-state
0036     //! version of the function was used, an error is triggered. When the
0037     //! stucture contains a single element and the no-state version of the
0038     //! function was used, that single element is returned as is.
0039     //!
0040     //!
0041     //! Signature
0042     //! ---------
0043     //! Given a `Foldable` `F` and an optional initial state of tag `S`,
0044     //! the signatures for `fold_right` are
0045     //! \f[
0046     //!     \mathtt{fold\_right} : F(T) \times S \times (T \times S \to S) \to S
0047     //! \f]
0048     //!
0049     //! for the variant with an initial state, and
0050     //! \f[
0051     //!     \mathtt{fold\_right} : F(T) \times (T \times T \to T) \to T
0052     //! \f]
0053     //!
0054     //! for the variant without an initial state.
0055     //!
0056     //! @param xs
0057     //! The structure to fold.
0058     //!
0059     //! @param state
0060     //! The initial value used for folding.
0061     //!
0062     //! @param f
0063     //! A binary function called as `f(x, state)`, where `state` is the
0064     //! result accumulated so far and `x` is an element in the structure.
0065     //! For right folds without an initial state, the function is called as
0066     //! `f(x1, x2)`, where `x1` and `x2` are elements of the structure.
0067     //!
0068     //!
0069     //! Example
0070     //! -------
0071     //! @include example/fold_right.cpp
0072 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0073     constexpr auto fold_right = [](auto&& xs[, auto&& state], auto&& f) -> decltype(auto) {
0074         return tag-dispatched;
0075     };
0076 #else
0077     template <typename T, typename = void>
0078     struct fold_right_impl : fold_right_impl<T, when<true>> { };
0079
0080     struct fold_right_t {
0081         template <typename Xs, typename State, typename F>
0082         constexpr decltype(auto) operator()(Xs&& xs, State&& state, F&& f) const;
0083
0084         template <typename Xs, typename F>
0085         constexpr decltype(auto) operator()(Xs&& xs, F&& f) const;
0086     };
0087
0088     BOOST_HANA_INLINE_VARIABLE constexpr fold_right_t fold_right{};
0089 #endif
0090 }} // end namespace boost::hana
0091
0092 #endif // !BOOST_HANA_FWD_FOLD_RIGHT_HPP