Difference between revisions of "cpp/iterator/next"
From cppreference.com
(p0031r0 (constexpr)) |
Andreas Krug (Talk | contribs) m (fmt, {{c}}) |
||
| (15 intermediate revisions by 7 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{cpp/title| next}} | + | {{cpp/title|next}} |
{{cpp/iterator/navbar}} | {{cpp/iterator/navbar}} | ||
{{dcl begin}} | {{dcl begin}} | ||
| − | {{dcl header | iterator}} | + | {{dcl header|iterator}} |
| − | {{dcl | | + | {{dcl rev multi |
| − | template< class | + | |since1=c++11|dcl1= |
| − | + | template< class InputIt > | |
| − | + | InputIt next( InputIt it, typename std::iterator_traits<InputIt>::difference_type n = 1 ); | |
| − | + | |since2=c++17|dcl2= | |
| − | + | ||
| − | + | ||
template< class InputIt > | template< class InputIt > | ||
| − | constexpr InputIt next( | + | constexpr |
| − | + | InputIt next( InputIt it, typename std::iterator_traits<InputIt>::difference_type n = 1 ); | |
| − | + | ||
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
| − | Return the {{c|n}}th successor of iterator {{c|it}}. | + | Return the {{c|n}}{{sup|th}} successor (or {{c|-n}}{{sup|th}} predecessor if {{c|n}} is negative) of iterator {{c|it}}. |
===Parameters=== | ===Parameters=== | ||
{{par begin}} | {{par begin}} | ||
| − | {{par | it | an iterator }} | + | {{par|it|an iterator}} |
| − | {{par | n | number of elements to advance}} | + | {{par|n|number of elements to advance}} |
{{par hreq}} | {{par hreq}} | ||
| − | {{par req | + | {{par req named|InputIt|InputIterator}} |
| − | + | ||
{{par end}} | {{par end}} | ||
===Return value=== | ===Return value=== | ||
| − | + | An iterator of type {{tt|InputIt}} that holds the {{c|n}}{{sup|th}} successor (or {{c|-n}}{{sup|th}} predecessor if {{c|n}} is negative) of iterator {{c|it}}. | |
| + | |||
| + | ===Complexity=== | ||
| + | Linear. | ||
| + | |||
| + | However, if {{tt|InputIt}} additionally meets the requirements of {{named req|RandomAccessIterator}}, complexity is constant. | ||
===Possible implementation=== | ===Possible implementation=== | ||
| − | {{eq fun | | + | {{eq fun|1= |
| − | template<class | + | template<class InputIt> |
| − | + | constexpr // since C++17 | |
| − | + | InputIt next(InputIt it, typename std::iterator_traits<InputIt>::difference_type n = 1) | |
{ | { | ||
std::advance(it, n); | std::advance(it, n); | ||
| Line 43: | Line 44: | ||
===Notes=== | ===Notes=== | ||
| − | Although the expression {{c|++c.begin()}} often compiles, it is not guaranteed to do so: {{c|c.begin()}} is an rvalue expression, and there is no {{ | + | Although the expression {{c|++c.begin()}} often compiles, it is not guaranteed to do so: {{c|c.begin()}} is an rvalue expression, and there is no {{named req|InputIterator}} requirement that specifies that increment of an rvalue is guaranteed to work. In particular, when iterators are implemented as pointers or its {{tt|operator++}} is lvalue-ref-qualified, {{c|++c.begin()}} does not compile, while {{c|std::next(c.begin())}} does. |
===Example=== | ===Example=== | ||
{{example | {{example | ||
| − | + | |code= | |
| − | + | ||
#include <iostream> | #include <iostream> | ||
#include <iterator> | #include <iterator> | ||
#include <vector> | #include <vector> | ||
| − | int main() | + | int main() |
{ | { | ||
| − | std::vector<int> v{ | + | std::vector<int> v{4, 5, 6}; |
| − | + | ||
| − | + | ||
| + | auto it = v.begin(); | ||
auto nx = std::next(it, 2); | auto nx = std::next(it, 2); | ||
| − | |||
std::cout << *it << ' ' << *nx << '\n'; | std::cout << *it << ' ' << *nx << '\n'; | ||
| + | |||
| + | it = v.end(); | ||
| + | nx = std::next(it, -2); | ||
| + | std::cout << ' ' << *nx << '\n'; | ||
} | } | ||
| − | + | |output= | |
| + | 4 6 | ||
| + | 5 | ||
}} | }} | ||
| + | |||
| + | ===Defect reports=== | ||
| + | {{dr list begin}} | ||
| + | {{dr list item|wg=lwg|dr=2353|std=C++11|before={{tt|next}} required {{named req|ForwardIterator}}|after={{named req|InputIterator}} allowed}} | ||
| + | {{dr list end}} | ||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc inc | cpp/iterator/dsc prev}} | + | {{dsc inc|cpp/iterator/dsc prev}} |
| − | {{dsc inc | cpp/iterator/dsc advance}} | + | {{dsc inc|cpp/iterator/dsc advance}} |
| + | {{dsc inc|cpp/iterator/dsc distance}} | ||
| + | {{dsc inc|cpp/iterator/ranges/dsc next}} | ||
{{dsc end}} | {{dsc end}} | ||
| − | + | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 08:24, 1 October 2023
| 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 |
(since C++17) | |
Return the nth successor (or -nth predecessor if n is negative) of iterator it.
Contents |
[edit] Parameters
| it | - | an iterator |
| n | - | number of elements to advance |
| Type requirements | ||
-InputIt must meet the requirements of LegacyInputIterator.
| ||
[edit] Return value
An iterator of type InputIt that holds the nth successor (or -nth predecessor if n is negative) of iterator it.
[edit] Complexity
Linear.
However, if InputIt additionally meets the requirements of LegacyRandomAccessIterator, complexity is constant.
[edit] 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; } |
[edit] 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.
[edit] 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
[edit] 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 |
[edit] See also
| (C++11) |
decrement an iterator (function template) |
| advances an iterator by given distance (function template) | |
| returns the distance between two iterators (function template) | |
| (C++20) |
increment an iterator by a given distance or to a bound (niebloid) |
