std::next

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Iterator library

Iterator primitives
iterator_traits
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag
iterator
Iterator adaptors
reverse_iterator move_iterator (C++11) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) back_inserter front_inserter inserter
Stream iterators
istream_iterator
ostream_iterator
istreambuf_iterator
ostreambuf_iterator
Iterator operations
advance
distance
prev (C++11)
next (C++11)
Range access
begincbegin (C++11)(C++14)
endcend (C++11)(C++14)
rbegincrbegin (C++14)(C++14)
rendcrend (C++14)(C++14)
Container access
sizessize (C++17)(C++20)
empty (C++17)
data (C++17)

 

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

Return the nth successor of iterator it.

Parameters

it	-	an iterator
n	-	number of elements to advance
Type requirements
- ForwardIt must meet the requirements of LegacyForwardIterator.
- InputIt must meet the requirements of LegacyInputIterator.

Return value

The nth successor of iterator it.

Complexity

Linear.

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

Possible implementation

template<class ForwardIt> ForwardIt next(ForwardIt it, typename std::iterator_traits<ForwardIt>::difference_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 LegacyBidirectionalIterator requirement that specifies that increment of an rvalue is guaranteed to work. In particular, when iterators are implemented as pointers, ++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{ 3, 1, 4 };
 
    auto it = v.begin();
 
    auto nx = std::next(it, 2);
 
    std::cout << *it << ' ' << *nx << '\n';
}

Output:

3 4

See also

prev (C++11)	decrement an iterator (function template)
advance	advances an iterator by given distance (function template)