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		     >
       (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
       iterator	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
       predecessor 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<In-
       putIt>::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		  2024.06.10			  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.1.quarterly>

home | help