std::iterator_traits

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms 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 Iterator > struct iterator_traits;
template< class T > struct iterator_traits<T*>;
template< class T > struct iterator_traits<const T*>;		(until C++20)

std::iterator_traits is the type trait class that provides uniform interface to the properties of LegacyIterator types. This makes it possible to implement algorithms only in terms of iterators.

The class defines the following types:

• difference_type - a signed integer type that can be used to identify distance between iterators
• value_type - the type of the values that can be obtained by dereferencing the iterator. This type is void for output iterators.
• pointer - defines a pointer to the type iterated over (value_type)
• reference - defines a reference to the type iterated over (value_type)
• iterator_category - the category of the iterator. Must be one of iterator category tags.

The template can be specialized for user-defined iterators so that the information about the iterator can be retrieved even if the type does not provide the usual typedefs.

Template parameters

Iterator

-

the iterator type to retrieve properties for

Member types

Member type	Definition
difference_type	Iterator::difference_type
value_type	Iterator::value_type
pointer	Iterator::pointer
reference	Iterator::reference
iterator_category	Iterator::iterator_category

If Iterator does not have all five member types difference_type, value_type, pointer, reference, and iterator_category, then this template has no members by any of those names (std::iterator_traits is SFINAE-friendly)

(since C++17)

Specializations

This type trait may be specialized for user-provided types that may be used as iterators. The standard library provides two partial specializations for pointer types T*, which makes it possible to use all iterator-based algorithms with raw pointers.

T* specialization member types

Member type	Definition
difference_type	std::ptrdiff_t
value_type	T (until C++20)std::remove_cv_t<T> (since C++20)
pointer	T*
reference	T&
iterator_category	std::random_access_iterator_tag

const T* specialization member types Member type Definition difference_type std::ptrdiff_t value_type T pointer const T* reference const T& iterator_category std::random_access_iterator_tag

(until C++20)

Example

The following example shows a general-purpose reverse() implementation for bidirectional iterators

Run this code

#include <iostream>
#include <iterator>
#include <vector>
#include <list>
 
template<class BidirIt>
void my_reverse(BidirIt first, BidirIt last)
{
    typename std::iterator_traits<BidirIt>::difference_type n = std::distance(first, last);
    --n;
    while(n > 0) {
        typename std::iterator_traits<BidirIt>::value_type tmp = *first;
        *first++ = *--last;
        *last = tmp;
        n -= 2;
    }
}
 
int main()
{
    std::vector<int> v{1, 2, 3, 4, 5};
    my_reverse(v.begin(), v.end());
    for (int n : v) {
        std::cout << n << ' ';
    }
    std::cout << '\n';
 
    std::list<int> l{1, 2, 3, 4, 5};
    my_reverse(l.begin(), l.end());
    for (auto n : l) {
        std::cout << n << ' ';
    }
    std::cout << '\n';
 
    int a[] = {1, 2, 3, 4, 5};
    my_reverse(a, a+5);
    for (int i=0; i<5; ++i) {
        std::cout << a[i] << ' ';
    }
    std::cout << '\n';
 
//    std::istreambuf_iterator<char> i1(std::cin), i2;
//    my_reverse(i1, i2); // compilation error
 
}

Output:

5 4 3 2 1
5 4 3 2 1
5 4 3 2 1

See also

iterator (deprecated in C++17)	base class to ease the definition of required types for simple iterators (class template)
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20)	empty class types used to indicate iterator categories (class)