hana/fwd/drop_front.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::drop_front`.
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_HPP
0011 #define BOOST_HANA_FWD_DROP_FRONT_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(xs, n)` is an
0023     //! 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     //! In case `length(xs) <= n`, `drop_front` will simply drop the whole
0029     //! iterable without failing, thus returning an empty iterable. This is
0030     //! different from `drop_front_exactly`, which expects `n <= length(xs)`
0031     //! but can be better optimized because of this additional guarantee.
0032     //!
0033     //!
0034     //! @param xs
0035     //! The iterable from which elements are dropped.
0036     //!
0037     //! @param n
0038     //! A non-negative `IntegralConstant` representing the number of elements
0039     //! to be dropped from the iterable. If `n` is not given, it defaults to
0040     //! an `IntegralConstant` with a value equal to `1`.
0041     //!
0042     //!
0043     //! Example
0044     //! -------
0045     //! @include example/drop_front.cpp
0046 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0047     constexpr auto drop_front = [](auto&& xs[, auto const& n]) {
0048         return tag-dispatched;
0049     };
0050 #else
0051     template <typename It, typename = void>
0052     struct drop_front_impl : drop_front_impl<It, when<true>> { };
0053
0054     struct drop_front_t {
0055         template <typename Xs, typename N>
0056         constexpr auto operator()(Xs&& xs, N const& n) const;
0057
0058         template <typename Xs>
0059         constexpr auto operator()(Xs&& xs) const;
0060     };
0061
0062     BOOST_HANA_INLINE_VARIABLE constexpr drop_front_t drop_front{};
0063 #endif
0064 }} // end namespace boost::hana
0065
0066 #endif // !BOOST_HANA_FWD_DROP_FRONT_HPP