boost/hana/fwd/group.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::group`.
   4
   5 @copyright Louis Dionne 2013-2017
   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_GROUP_HPP
  11 #define BOOST_HANA_FWD_GROUP_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/core/when.hpp>
  15 #include <boost/hana/detail/nested_by_fwd.hpp>
  16
  17
  18 BOOST_HANA_NAMESPACE_BEGIN
  19     //! Group adjacent elements of a sequence that all respect a binary
  20     //! predicate, by default equality.
  21     //! @ingroup group-Sequence
  22     //!
  23     //! Given a _finite_ Sequence and an optional predicate (by default
  24     //! `equal`), `group` returns a sequence of subsequences representing
  25     //! groups of adjacent elements that are "equal" with respect to the
  26     //! predicate. In other words, the groups are such that the predicate is
  27     //! satisfied when it is applied to any two adjacent elements in that
  28     //! group. The sequence returned by `group` is such that the concatenation
  29     //! of its elements is equal to the original sequence, which is equivalent
  30     //! to saying that the order of the elements is not changed.
  31     //!
  32     //! If no predicate is provided, adjacent elements in the sequence must
  33     //! all be compile-time `Comparable`.
  34     //!
  35     //!
  36     //! Signature
  37     //! ---------
  38     //! Given a Sequence `s` with tag `S(T)`, an `IntegralConstant` `Bool`
  39     //! holding a value of type `bool`, and a predicate
  40     //! \f$ pred : T \times T \to Bool \f$, `group` has the following
  41     //! signatures. For the variant with a provided predicate,
  42     //! \f[
  43     //!     \mathtt{group} : S(T) \times (T \times T \to Bool) \to S(S(T))
  44     //! \f]
  45     //!
  46     //! for the variant without a custom predicate, `T` is required to be
  47     //! Comparable. The signature is then
  48     //! \f[
  49     //!     \mathtt{group} : S(T) \to S(S(T))
  50     //! \f]
  51     //!
  52     //! @param xs
  53     //! The sequence to split into groups.
  54     //!
  55     //! @param predicate
  56     //! A binary function called as `predicate(x, y)`, where `x` and `y` are
  57     //! _adjacent_ elements in the sequence, whether both elements should be
  58     //! in the same group (subsequence) of the result. In the current version
  59     //! of the library, the result returned by `predicate` must be an
  60     //! `IntegralConstant` holding a value of a type convertible to `bool`.
  61     //! Also, `predicate` has to define an equivalence relation as defined by
  62     //! the `Comparable` concept. When this predicate is not provided, it
  63     //! defaults to `equal`, which requires the comparison of any two adjacent
  64     //! elements in the sequence to return a boolean `IntegralConstant`.
  65     //!
  66     //!
  67     //! Syntactic sugar (`group.by`)
  68     //! ----------------------------
  69     //! `group` can be called in a third way, which provides a nice syntax
  70     //! especially when working with the `comparing` combinator:
  71     //! @code
  72     //!     group.by(predicate, xs) == group(xs, predicate)
  73     //!     group.by(predicate) == group(-, predicate)
  74     //! @endcode
  75     //!
  76     //! where `group(-, predicate)` denotes the partial application of
  77     //! `group` to `predicate`.
  78     //!
  79     //!
  80     //! Example
  81     //! -------
  82     //! @include example/group.cpp
  83 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  84     constexpr auto group = [](auto&& xs[, auto&& predicate]) {
  85         return tag-dispatched;
  86     };
  87 #else
  88     template <typename S, typename = void>
  89     struct group_impl : group_impl<S, when<true>> { };
  90
  91     struct group_t : detail::nested_by<group_t> {
  92         template <typename Xs>
  93         constexpr auto operator()(Xs&& xs) const;
  94
  95         template <typename Xs, typename Predicate>
  96         constexpr auto operator()(Xs&& xs, Predicate&& pred) const;
  97     };
  98
  99     constexpr group_t group{};
 100 #endif
 101 BOOST_HANA_NAMESPACE_END
 102
 103 #endif // !BOOST_HANA_FWD_GROUP_HPP