Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::ranges::next(3)	      C++ Standard Libary	  std::ranges::next(3)

NAME
       std::ranges::next - std::ranges::next

Synopsis
	  Defined in header <iterator>
	  Call signature
	  template<	     std::input_or_output_iterator	   I	     >
       (1) (since C++20)
	  constexpr I next( I i	);
	  template<	    std::input_or_output_iterator	  I	     >
       (2) (since C++20)
	  constexpr I next( I i, std::iter_difference_t<I> n );
	  template< std::input_or_output_iterator I, std::sentinel_for<I> S
	  >
       (3) (since C++20)
	  constexpr I next( I i, S bound );
	  template< std::input_or_output_iterator I, std::sentinel_for<I> S
	  >
       (4) (since C++20)
	  constexpr I next( I i, std::iter_difference_t<I> n, S	bound );

	  Return the n^th successor of iterator	i.

	  The  function-like  entities	described  on this page	are niebloids,
       that is:

	    * Explicit template	argument lists cannot be specified when	 call-
       ing any of them.
	    * None of them are visible to argument-dependent lookup.
	    *  When  any of them are found by normal unqualified lookup	as the
       name to the left
	      of the function-call operator, argument-dependent	lookup is  in-
       hibited.

	  In  practice,	 they  may be implemented as function objects, or with
       special compiler
	  extensions.

Parameters
	  i	- an iterator
	  n	- number of elements to	advance
	  bound	- sentinel denoting the	end of the range i points to

Return value
	  1) The successor of iterator i.
	  2) The n^th successor	of iterator i.
	  3) The first iterator	equivalent to bound.
	  4) The n^th successor	of iterator i, or the first  iterator  equiva-
       lent to bound,
	  whichever is first.

Complexity
	  1) Constant.
	  2)  Constant if I models std::random_access_iterator;	otherwise lin-
       ear.
	  3) Constant if I and S  models  both	std::random_access_iterator<I>
       and
	  std::sized_sentinel_for<S,  I>,  or  if I and	S models std::assigna-
       ble_from<I&, S>;
	  otherwise linear.
	  4) Constant if I and S  models  both	std::random_access_iterator<I>
       and
	  std::sized_sentinel_for<S, I>; otherwise linear.

Possible implementation
	  struct next_fn
	  {
	      template<std::input_or_output_iterator I>
	      constexpr	I operator()(I i) const
	      {
		  ++i;
		  return i;
	      }

	      template<std::input_or_output_iterator I>
	      constexpr	I operator()(I i, std::iter_difference_t<I> n) const
	      {
		  ranges::advance(i, n);
		  return i;
	      }

	      template<std::input_or_output_iterator  I,  std::sentinel_for<I>
       S>
	      constexpr	I operator()(I i, S bound) const
	      {
		  ranges::advance(i, bound);
		  return i;
	      }

	      template<std::input_or_output_iterator  I,  std::sentinel_for<I>
       S>
	      constexpr	 I  operator()(I  i,  std::iter_difference_t<I>	 n,  S
       bound) const
	      {
		  ranges::advance(i, n,	bound);
		  return i;
	      }
	  };

	  inline constexpr auto	next = next_fn();

Notes
	  Although the expression ++x.begin() often compiles, it is not	 guar-
       anteed to do so:
	  x.begin()  is	an rvalue expression, and there	is no requirement that
       specifies that
	  increment of an rvalue is guaranteed to work.	 In  particular,  when
       iterators are
	  implemented  as  pointers or its operator++ is lvalue-ref-qualified,
       ++x.begin() does
	  not compile, while ranges::next(x.begin()) does.

Example
       // Run this code

	#include <cassert>
	#include <iterator>

	int main()
	{
	    auto v = {3, 1, 4};
	    {
		auto n = std::ranges::next(v.begin());
		assert(*n == 1);
	    }
	    {
		auto n = std::ranges::next(v.begin(), 2);
		assert(*n == 4);
	    }
	    {
		auto n = std::ranges::next(v.begin(), v.end());
		assert(n == v.end());
	    }
	    {
		auto n = std::ranges::next(v.begin(), 42, v.end());
		assert(n == v.end());
	    }
	}

See also
	  ranges::prev	  decrement an iterator	by a given distance  or	 to  a
       bound
	  (C++20)	  (niebloid)
	  ranges::advance advances an iterator by given	distance or to a given
       bound
	  (C++20)	  (niebloid)
	  next		  increment an iterator
	  (C++11)	  (function template)

http://cppreference.com		  2024.06.10		  std::ranges::next(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::ranges::next&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help