Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/iterator/next"

From cppreference.com
< cpp‎ | iterator
m (Text replace - "{{concept" to "{{named req")
m (fmt, {{c}})
 
(12 intermediate revisions by 6 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 | 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( InputIt it, typename std::iterator_traits<InputIt>::difference_type n = 1 );
−
  typename std::iterator_traits<ForwardIt>::difference_type n {{=}} 1 );
+
|since2=c++17|dcl2=
−
}}
+
−
{{dcl | since=c++17 |
+
 
template< class InputIt >
 
template< class InputIt >
−
constexpr InputIt next(
+
constexpr
−
  InputIt it,  
+
InputIt next( InputIt it, typename std::iterator_traits<InputIt>::difference_type n = 1 );
−
  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 concept | ForwardIt | ForwardIterator}}
+
{{par req named|InputIt|InputIterator}}
−
{{par req concept | InputIt | InputIterator}}
+
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
The {{c|n}}th successor of iterator {{c|it}}.
+
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 ForwardIt>
+
template<class InputIt>
−
ForwardIt next(ForwardIt it,
+
constexpr // since C++17
−
              typename std::iterator_traits<ForwardIt>::difference_type n {{=}} 1)
+
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 {{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|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=
−
| code=
+
 
#include <iostream>
 
#include <iostream>
 
#include <iterator>
 
#include <iterator>
 
#include <vector>
 
#include <vector>
  
−
int main()  
+
int main()
 
{
 
{
−
     std::vector<int> v{ 3, 1, 4 };
+
     std::vector<int> v{4, 5, 6};
−
   
+
−
    auto it = v.begin();
+
  
 +
    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=3 4
+
|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}}
  
−
[[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]]
+

Latest revision as of 08:24, 1 October 2023

 
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 (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) [edit]
advances an iterator by given distance
(function template) [edit]
returns the distance between two iterators
(function template) [edit]
(C++20)
 increment an iterator by a given distance or to a bound
(niebloid)[edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/iterator/next&oldid=159945"