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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::next - std::next

Synopsis
	  Defined in header <iterator>
	  template< class InputIt >

	  InputIt							 next(
       (since C++11)
	  InputIt							   it,
       (until C++17)

	  typename std::iterator_traits<InputIt>::difference_type n = 1	);
	  template< class InputIt >

	  constexpr			   InputIt			 next(
       (since C++17)
	  InputIt it,

	  typename std::iterator_traits<InputIt>::difference_type n = 1	);

	  Return the nth successor of iterator it.

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

Type requirements
	  -
	  InputIt must meet the	requirements of	LegacyInputIterator.

Return value
	  The nth successor 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>::difference_type
       n = 1)
	  {
	      std::advance(it, n);
	      return it;
	  }

Notes
	  Although the expression ++c.begin() often compiles, it is not	 guar-
       anteed to do so:
	  c.begin() is an rvalue expression, and there is no LegacyInputItera-
       tor 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
       behavior
	  LWG 2353 C++11      next  required  LegacyForwardIterator  LegacyIn-
       putIterator 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		  2022.07.31			  std::next(3)

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

home | help