std::input_iterator_tag, std::output_iterator_tag, std::forward_iterator_tag, std::bidirectional_iterator_tag, std::random_access_iterator_tag, std::contiguous_iterator_tag

 

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

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Iterator library

Iterator concepts
indirectly_readable (C++20) indirectly_writable (C++20) weakly_incrementable (C++20) incrementable (C++20) input_or_output_iterator (C++20) sentinel_for (C++20) sized_sentinel_for (C++20)	input_iterator (C++20) output_iterator (C++20) forward_iterator (C++20) bidirectional_iterator (C++20) random_access_iterator (C++20) contiguous_iterator (C++20)
Iterator primitives
iterator_traits input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20) iterator (deprecated in C++17)	incrementable_traits (C++20) indirectly_readable_traits (C++20) iter_value_titer_difference_titer_reference_titer_rvalue_reference_titer_common_reference_t (C++20)(C++20)(C++20)(C++20)(C++20)
Algorithm concepts and utilities
Indirect callable concepts
indirectly_unary_invocableindirectly_regular_unary_invocable (C++20)(C++20) indirect_unary_predicate (C++20)	indirect_binary_predicate (C++20) indirect_equivalence_relation (C++20) indirect_strict_weak_order (C++20)
Common algorithm requirements
indirectly_movable (C++20) indirectly_movable_storable (C++20) indirectly_copyable (C++20) indirectly_copyable_storable (C++20)	indirectly_swappable (C++20) indirectly_comparable (C++20) permutable (C++20) mergeable (C++20) sortable (C++20)
Utilities
indirect_result_t	projected
Iterator adaptors
reverse_iterator move_iterator (C++11) move_sentinel (C++20) common_iterator (C++20) counted_iterator (C++20) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) default_sentinel_tdefault_sentinel (C++20)(C++20) unreachable_sentinel_tunreachable_sentinel (C++20)(C++20) back_inserter front_inserter inserter
Stream iterators
istream_iterator ostream_iterator	istreambuf_iterator ostreambuf_iterator
Iterator customization points
ranges::iter_move (C++20)
ranges::iter_swap (C++20)
Iterator operations
advance distance prev (C++11) next (C++11)	ranges::advance (C++20) ranges::distance (C++20) ranges::prev (C++20) ranges::next (C++20)
Range access
begincbegin (C++11)(C++14) endcend (C++11)(C++14) sizessize (C++17)(C++20)	rbegincrbegin (C++14)(C++14) rendcrend (C++14)(C++14) empty (C++17) data (C++17)

 

Defined in header <iterator>
struct input_iterator_tag { };	(1)
struct output_iterator_tag { };	(2)
struct forward_iterator_tag : public input_iterator_tag { };	(3)
struct bidirectional_iterator_tag : public forward_iterator_tag { };	(4)
struct random_access_iterator_tag : public bidirectional_iterator_tag { };	(5)
struct contiguous_iterator_tag: public random_access_iterator_tag { };	(6)	(since C++20)

Defines the category of an iterator. Each tag is an empty type and corresponds to one of the five (until C++20)six (since C++20) iterator categories:

1) input_iterator_tag corresponds to LegacyInputIterator.

2) output_iterator_tag corresponds to LegacyOutputIterator.

3) forward_iterator_tag corresponds to LegacyForwardIterator.

4) bidirectional_iterator_tag corresponds to LegacyBidirectionalIterator.

5) random_access_iterator_tag corresponds to LegacyRandomAccessIterator.

6) contiguous_iterator_tag corresponds to LegacyContiguousIterator.

Iterator category tags carry information that can be used to select the most efficient algorithms for the specific requirement set that is implied by the category.

For every iterator type It, a typedef std::iterator_traits<It>::iterator_category is available, which is an alias to one of these five (until C++20)six (since C++20) tag types.

Additionally, std::iterator_traits<It>::iterator_concept may be declared as an alias to one of these tags, to indicate conformance to the iterator concepts (provided that the iterator also satisfies other requirements as declared in the concepts).

(since C++20)

Notes There is no separate tag for LegacyContiguousIterator.

(since C++17) (until C++20)

Example

Common technique for algorithm selection based on iterator category tags is to use a dispatcher function (the alternative is std::enable_if)

Run this code

#include <iostream>
#include <vector>
#include <list>
#include <iterator>
 
// quite often implementation details are hidden in a dedicated namespace
namespace implementation_details {
template<class BDIter>
void alg(BDIter, BDIter, std::bidirectional_iterator_tag)
{
    std::cout << "alg() called for bidirectional iterator\n";
}
 
template<class RAIter>
void alg(RAIter, RAIter, std::random_access_iterator_tag)
{
    std::cout << "alg() called for random-access iterator\n";
}
} // namespace implementation_details
 
template<class Iter>
void alg(Iter first, Iter last)
{
    implementation_details::alg(first, last,
        typename std::iterator_traits<Iter>::iterator_category());
}
 
int main()
{
    std::vector<int> v;
    alg(v.begin(), v.end());
 
    std::list<int> l;
    alg(l.begin(), l.end());
 
//    std::istreambuf_iterator<char> i1(std::cin), i2;
//    alg(i1, i2); // compile error: no matching function for call
}

Output:

alg() called for random-access iterator
alg() called for bidirectional iterator

See also

iterator (deprecated in C++17)	base class to ease the definition of required types for simple iterators (class template)
iterator_traits	provides uniform interface to the properties of an iterator (class template)