Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/iterator/next"

From cppreference.com
< cpp‎ | iterator
(Corrected identifier.)
(LWG2353, add notes)
Line 3: Line 3:
 
{{dcl begin}}
 
{{dcl begin}}
 
{{dcl header | iterator}}
 
{{dcl header | iterator}}
−
{{dcl | since=c++11 | notes={{mark until c++17}} |
+
{{dcl rev multi
−
template< class ForwardIt >
+
| since1=c++11 | dcl1=
−
ForwardIt next(
+
template< class InputIt >
−
   ForwardIt it,  
+
InputIt next(
−
   typename std::iterator_traits<ForwardIt>::difference_type n {{=}} 1 );
+
   InputIt it,  
−
}}
+
   typename std::iterator_traits<InputIt>::difference_type n = 1 );
−
{{dcl | since=c++17 |
+
| since2=c++17 | dcl2=
 
template< class InputIt >
 
template< class InputIt >
 
constexpr InputIt next(
 
constexpr InputIt next(
 
   InputIt it,  
 
   InputIt it,  
−
   typename std::iterator_traits<InputIt>::difference_type n {{=}} 1 );
+
   typename std::iterator_traits<InputIt>::difference_type n = 1 );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
Line 24: Line 24:
 
{{par | n | number of elements to advance}}
 
{{par | n | number of elements to advance}}
 
{{par hreq}}
 
{{par hreq}}
−
{{par req named | ForwardIt | ForwardIterator}}
 
 
{{par req named | InputIt | InputIterator}}
 
{{par req named | InputIt | InputIterator}}
 
{{par end}}
 
{{par end}}
Line 37: Line 36:
  
 
===Possible implementation===
 
===Possible implementation===
−
{{eq fun |
+
{{eq fun |1=
−
template<class ForwardIt>
+
template<class InputIt>
−
ForwardIt next(ForwardIt it,
+
constexpr // since C++17
−
               typename std::iterator_traits<ForwardIt>::difference_type n {{=}} 1)
+
ForwardIt next(InputIt it,
 +
               typename std::iterator_traits<ForwardIt>::difference_type n = 1)
 
{
 
{
 
     std::advance(it, n);
 
     std::advance(it, n);
Line 48: Line 48:
  
 
===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 {{named req|BidirectionalIterator}} requirement that specifies that increment of an rvalue is guaranteed to work. In particular, when iterators are implemented as pointers, {{c|++c.begin()}} does not compile, while {{c|std::next(c.begin())}} does.
+
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|BidirectionalIterator}} 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===
Line 70: Line 70:
 
  | output=3 4
 
  | output=3 4
 
}}
 
}}
 +
 +
===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===
Line 77: Line 82:
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/iterator/next]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/iterator/next]]
+
−
[[fr:cpp/iterator/next]]
+
−
[[it:cpp/iterator/next]]
+
−
[[ja:cpp/iterator/next]]
+
−
[[pt:cpp/iterator/next]]
+
−
[[ru:cpp/iterator/next]]
+
−
[[zh:cpp/iterator/next]]
+

Revision as of 09:08, 11 July 2020

 
C++
 
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
(C++20)
(C++20)
(C++20)
Utilities
(C++20)
Iterator adaptors
Range access
(C++11)(C++14)
(C++14)(C++14)  
(C++11)(C++14)
(C++14)(C++14)  
(C++17)(C++20)
(C++17)
(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.

Contents

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

(C++11)
 decrement an iterator
(function template) [edit]
advances an iterator by given distance
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/iterator/next&oldid=120786"