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 nth successor of iterator i.

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

	    * Explicit template	argument lists may not be specified when call-
       ing any of them.
	    * None of them is visible to argument-dependent lookup.
	    * When one of them is found	by normal unqualified lookup  for  the
       name to the left
	      of  the  function-call  operator,	it inhibits argument-dependent
       lookup.

	  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 nth successor of iterator i
	  3) The first iterator	equivalent to bound
	  4) The nth successor of iterator i, or the first iterator equivalent
       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 <iomanip>
	#include <iostream>
	#include <iterator>
	#include <vector>

	int main()
	{
	    std::cout << std::boolalpha;
	    std::vector<int> v{	3, 1, 4	};
	    {
		auto n = std::ranges::next(v.begin());
		std::cout << *n	<< '\n';
	    }
	    {
		auto n = std::ranges::next(v.begin(), 2);
		std::cout << *n	<< '\n';
	    }
	    {
		auto n = std::ranges::next(v.begin(), v.end());
		std::cout << (n	== v.end()) << '\n';
	    }
	    {
		auto n = std::ranges::next(v.begin(), 42, v.end());
		std::cout << (n	== v.end()) << '\n';
	    }
	}

Output:
	1
	4
	true
	true

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		  2022.07.31		  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.0>

home | help