unfold_left.hpp 2.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
  1. /*!
  2. @file
  3. Forward declares `boost::hana::unfold_left`.
  4. @copyright Louis Dionne 2013-2017
  5. Distributed under the Boost Software License, Version 1.0.
  6. (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
  7. */
  8. #ifndef BOOST_HANA_FWD_UNFOLD_LEFT_HPP
  9. #define BOOST_HANA_FWD_UNFOLD_LEFT_HPP
  10. #include <boost/hana/config.hpp>
  11. #include <boost/hana/core/when.hpp>
  12. BOOST_HANA_NAMESPACE_BEGIN
  13. //! Dual operation to `fold_left` for sequences.
  14. //! @ingroup group-Sequence
  15. //!
  16. //! While `fold_left` reduces a structure to a summary value from the left,
  17. //! `unfold_left` builds a sequence from a seed value and a function,
  18. //! starting from the left.
  19. //!
  20. //!
  21. //! Signature
  22. //! ---------
  23. //! Given a `Sequence` `S`, an initial value `state` of tag `I`, an
  24. //! arbitrary Product `P` and a function \f$ f : I \to P(I, T) \f$,
  25. //! `unfold_left<S>` has the following signature:
  26. //! \f[
  27. //! \mathtt{unfold\_left}_S : I \times (I \to P(I, T)) \to S(T)
  28. //! \f]
  29. //!
  30. //! @tparam S
  31. //! The tag of the sequence to build up.
  32. //!
  33. //! @param state
  34. //! An initial value to build the sequence from.
  35. //!
  36. //! @param f
  37. //! A function called as `f(state)`, where `state` is an initial value,
  38. //! and returning
  39. //! 1. `nothing` if it is done producing the sequence.
  40. //! 2. otherwise, `just(make<P>(state, x))`, where `state` is the new
  41. //! initial value used in the next call to `f`, `x` is an element to
  42. //! be appended to the resulting sequence, and `P` is an arbitrary
  43. //! `Product`.
  44. //!
  45. //!
  46. //! Fun fact
  47. //! ---------
  48. //! In some cases, `unfold_left` can undo a `fold_left` operation:
  49. //! @code
  50. //! unfold_left<S>(fold_left(xs, state, f), g) == xs
  51. //! @endcode
  52. //!
  53. //! if the following holds
  54. //! @code
  55. //! g(f(x, y)) == just(make_pair(x, y))
  56. //! g(state) == nothing
  57. //! @endcode
  58. //!
  59. //!
  60. //! Example
  61. //! -------
  62. //! @include example/unfold_left.cpp
  63. #ifdef BOOST_HANA_DOXYGEN_INVOKED
  64. template <typename S>
  65. constexpr auto unfold_left = [](auto&& state, auto&& f) {
  66. return tag-dispatched;
  67. };
  68. #else
  69. template <typename S, typename = void>
  70. struct unfold_left_impl : unfold_left_impl<S, when<true>> { };
  71. template <typename S>
  72. struct unfold_left_t;
  73. template <typename S>
  74. constexpr unfold_left_t<S> unfold_left{};
  75. #endif
  76. BOOST_HANA_NAMESPACE_END
  77. #endif // !BOOST_HANA_FWD_UNFOLD_LEFT_HPP