hana/fwd/fold_left.hpp

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