table of contents
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
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 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 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)
2022.07.31 | http://cppreference.com |