std::next

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Iterator library

Iterator concepts
indirectly_readable (C++20) indirectly_writable (C++20) weakly_incrementable (C++20) incrementable (C++20) is-integer-like is-signed-integer-like (C++20)(C++20)	sentinel_for (C++20) sized_sentinel_for (C++20) input_iterator (C++20) output_iterator (C++20) input_or_output_iterator (C++20)	forward_iterator (C++20) bidirectional_iterator (C++20) random_access_iterator (C++20) contiguous_iterator (C++20)
Iterator primitives
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20)	iter_value_titer_difference_titer_reference_titer_const_reference_titer_rvalue_reference_titer_common_reference_t (C++20)(C++20)(C++20)(C++23)(C++20)(C++20)	iterator (deprecated in C++17) iterator_traits incrementable_traits (C++20) indirectly_readable_traits (C++20)
Algorithm concepts and utilities
Indirect callable concepts
indirectly_unary_invocableindirectly_regular_unary_invocable (C++20)(C++20)	indirect_unary_predicate (C++20) indirect_binary_predicate (C++20)	indirect_equivalence_relation (C++20) indirect_strict_weak_order (C++20)
Common algorithm requirements
indirectly_movable (C++20) indirectly_movable_storable (C++20) indirectly_copyable (C++20)	indirectly_copyable_storable (C++20)   indirectly_swappable (C++20) indirectly_comparable (C++20)	permutable (C++20) mergeable (C++20) sortable (C++20)
Utilities
indirect_result_t (C++20)	projected (C++20)	projected_value_t (C++26)
Iterator adaptors
reverse_iterator make_reverse_iterator (C++14) move_iterator (C++11) make_move_iterator (C++11) default_sentinel_tdefault_sentinel (C++20)(C++20) unreachable_sentinel_tunreachable_sentinel (C++20)(C++20)	front_insert_iterator back_insert_iterator inserter insert_iterator front_inserter back_inserter move_sentinel (C++20)	common_iterator (C++20) counted_iterator (C++20) basic_const_iterator (C++23) const_iterator (C++23) const_sentinel (C++23) make_const_iterator (C++23) make_const_sentinel (C++23)
Stream iterators istream_iterator    ostream_iterator istreambuf_iterator ostreambuf_iterator	Iterator customization points ranges::iter_move (C++20) ranges::iter_swap (C++20)
Iterator operations advance distance prev (C++11)   next (C++11) ranges::advance (C++20) ranges::distance (C++20) ranges::prev (C++20) ranges::next (C++20)	Range access begincbegin (C++11)(C++14) rbegincrbegin (C++14)(C++14)   endcend (C++11)(C++14) rendcrend (C++14)(C++14)   sizessize (C++17)(C++20) empty (C++17) data (C++17)

 

Defined in header <iterator>
template< class InputIt > InputIt next(   InputIt it,   typename std::iterator_traits<InputIt>::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
- 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 InputIt> constexpr // since C++17 ForwardIt next(InputIt 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 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{ 3, 1, 4 };
 
    auto it = v.begin();
 
    auto nx = std::next(it, 2);
 
    std::cout << *it << ' ' << *nx << '\n';
}

Output:

3 4

Defect reports

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

DR	Applied to	Behavior as published	Correct behavior
LWG 2353	C++11	next required LegacyForwardIterator	LegacyInputIterator allowed

See also

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