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

NAME
     std::next - std::next

Synopsis
	Defined in header <iterator>
	template<		  class 		InputIt 	       >
     (since C++11)
	InputIt 	 next(		InputIt 	  it,		typename
     (until C++17)
	std::iterator_traits<InputIt>::difference_type n = 1 );
	template< class InputIt >

	constexpr
     (since C++17)

	InputIt next( InputIt it, typename
	std::iterator_traits<InputIt>::difference_type n = 1 );

	Return the n^th successor (or -n^th predecessor if n is negative) of it-
     erator it.

Parameters
	it	   -	     an iterator
	n	   -	     number of elements to advance

Type requirements
	-
	InputIt must meet the requirements of LegacyInputIterator.

Return value
	An iterator of type InputIt that holds the n^th successor (or -n^th pre-
     decessor if n
	is negative) of iterator it.

Complexity
	Linear.

	However, if InputIt additionally meets the requirements of
	LegacyRandomAccessIterator, complexity is constant.

Possible implementation
	template<class InputIt>
	constexpr // since C++17
	InputIt next(InputIt it, typename std::iterator_traits<InputIt>::differ-
     ence_type n = 1)
	{
	    std::advance(it, n);
	    return it;
	}

Notes
	Although the expression ++c.begin() often compiles, it is not guaranteed
     to do so:
	c.begin()  is  an rvalue expression, and there is no LegacyInputIterator
     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,	 ++c.begin()	does	not    compile,    while
     std::next(c.begin()) does.

Example
     // Run this code

      #include <iostream>
      #include <iterator>
      #include <vector>

      int main()
      {
	  std::vector<int> v{4, 5, 6};

	  auto it = v.begin();
	  auto nx = std::next(it, 2);
	  std::cout << *it << ' ' << *nx << '\n';

	  it = v.end();
	  nx = std::next(it, -2);
	  std::cout << ' ' << *nx << '\n';
      }

Output:
      4 6
       5

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	   Behavior as published	     Correct be-
     havior
	LWG 2353 C++11	    next required LegacyForwardIterator LegacyInputIter-
     ator allowed

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

http://cppreference.com 	   2024.06.10			    std::next(3)
home | help