hana/fwd/drop_front_exactly.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::drop_front_exactly`.
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_DROP_FRONT_EXACTLY_HPP
0011 #define BOOST_HANA_FWD_DROP_FRONT_EXACTLY_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! Drop the first `n` elements of an iterable, and return the rest.
0019     //! @ingroup group-Iterable
0020     //!
0021     //! Given an `Iterable` `xs` with a linearization of `[x1, x2, ...]` and
0022     //! a non-negative `IntegralConstant` `n`, `drop_front_exactly(xs, n)` is
0023     //! an iterable with the same tag as `xs` whose linearization is
0024     //! `[xn+1, xn+2, ...]`. In particular, note that this function does not
0025     //! mutate the original iterable in any way. If `n` is not given, it
0026     //! defaults to an `IntegralConstant` with a value equal to `1`.
0027     //!
0028     //! It is an error to use `drop_front_exactly` with `n > length(xs)`. This
0029     //! additional guarantee allows `drop_front_exactly` to be better optimized
0030     //! than the `drop_front` function, which allows `n > length(xs)`.
0031     //!
0032     //!
0033     //! @param xs
0034     //! The iterable from which elements are dropped.
0035     //!
0036     //! @param n
0037     //! A non-negative `IntegralConstant` representing the number of elements
0038     //! to be dropped from the iterable. In addition to being non-negative,
0039     //! `n` must be less than or equal to the number of elements in `xs`.
0040     //! If `n` is not given, it defaults to an `IntegralConstant` with a value
0041     //! equal to `1`.
0042     //!
0043     //!
0044     //! Example
0045     //! -------
0046     //! @include example/drop_front_exactly.cpp
0047 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0048     constexpr auto drop_front_exactly = [](auto&& xs[, auto const& n]) {
0049         return tag-dispatched;
0050     };
0051 #else
0052     template <typename It, typename = void>
0053     struct drop_front_exactly_impl : drop_front_exactly_impl<It, when<true>> { };
0054
0055     struct drop_front_exactly_t {
0056         template <typename Xs, typename N>
0057         constexpr auto operator()(Xs&& xs, N const& n) const;
0058
0059         template <typename Xs>
0060         constexpr auto operator()(Xs&& xs) const;
0061     };
0062
0063     BOOST_HANA_INLINE_VARIABLE constexpr drop_front_exactly_t drop_front_exactly{};
0064 #endif
0065 }} // end namespace boost::hana
0066
0067 #endif // !BOOST_HANA_FWD_DROP_FRONT_EXACTLY_HPP