std::advance

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Iterator library

Iterator primitives
iterator_traits
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag
iterator
Iterator adaptors
reverse_iterator move_iterator (C++11) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) back_inserter front_inserter inserter
Stream iterators
istream_iterator
ostream_iterator
istreambuf_iterator
ostreambuf_iterator
Iterator operations
advance
distance
prev (C++11)
next (C++11)
Range access
begincbegin (C++11)(C++14)
endcend (C++11)(C++14)
rbegincrbegin (C++14)(C++14)
rendcrend (C++14)(C++14)
Container access
size (C++17)
empty (C++17)
data (C++17)

Defined in header <iterator>
template< class InputIt, class Distance > void advance( InputIt& it, Distance n );		(until C++17)
template< class InputIt, class Distance > constexpr void advance( InputIt& it, Distance n );		(since C++17)

Increments given iterator it by n elements.

If n is negative, the iterator is decremented. In this case, InputIt must meet the requirements of BidirectionalIterator, otherwise the behavior is undefined.

Parameters

it	-	iterator to be advanced
n	-	number of elements it should be advanced
Type requirements
- InputIt must meet the requirements of InputIterator.

Return value

(none)

Complexity

Linear.

However, if InputIt additionally meets the requirements of RandomAccessIterator, complexity is constant.

Notes

The behavior is undefined if the specified sequence of increments or decrements would require that a non-incrementable iterator (such as the past-the-end iterator) is incremented, or that a non-decrementable iterator (such as the front iterator or the singular iterator) is decremented.

Example

Run this code

#include <iostream>
#include <iterator>
#include <vector>

int main() 
{
    std::vector<int> v{ 3, 1, 4 };

    auto vi = v.begin();

    std::advance(vi, 2);

    std::cout << *vi << '\n';
}

Output:

4

See also

next (C++11)	increment an iterator (function)
distance	returns the distance between two iterators (function)