< cpp‎ | iterator
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
Iterator adaptors
Stream iterators
Iterator customization points
Iterator operations
Range access
Defined in header <iterator>
template< std::input_or_output_iterator I >
class counted_iterator;
(since C++20)

std::counted_iterator is an iterator adaptor which behaves exactly like the underlying iterator, except that it keeps track of the distance to the end of its range. This iterator is equal to std::default_sentinel if and only if its count reaches zero.


[edit] Member types

Member type Definition
iterator_type I
value_type std::iter_value_t<I> If I models indirectly_readable; otherwise, not defined
difference_type std::iter_difference_t<I>
iterator_concept I::iterator_concept if present; otherwise, not defined
iterator_category I::iterator_category if present; otherwise, not defined

[edit] Member functions

constructs a new iterator adaptor
(public member function) [edit]
assigns another iterator adaptor
(public member function) [edit]
accesses the underlying iterator
(public member function) [edit]
returns the distance to the end
(public member function) [edit]
accesses the pointed-to element
(public member function) [edit]
accesses an element by index
(public member function) [edit]
advances or decrements the iterator
(public member function) [edit]

[edit] Member objects

Member name Definition
current (private) the underlying iterator from which base() copies, the name is for exposition only
length (private) the distance between the underlying iterator and the end of its range, the name is for exposition only

[edit] Non-member functions

compares the distances to the end
(function template) [edit]
checks if the distance to the end is equal to ​0​
(function template) [edit]
advances the iterator
(function template) [edit]
computes the distance between two iterator adaptors
(function template) [edit]
computes the signed distance to the end
(function template) [edit]
casts the result of dereferencing the underlying iterator to its associated rvalue reference type
(function template) [edit]
swaps the objects pointed to by two underlying iterators
(function template) [edit]

[edit] Helper classes

provides uniform interface to the properties of the std::counted_iterator type
(class template specialization) [edit]

[edit] Example

#include <algorithm>
#include <iostream>
#include <iterator>
#include <string>
#include <vector>
using std::operator""s;
void print(auto const remark, auto const& v) {
    const auto size = std::ssize(v);
    std::cout << remark << "[" << size << "] { ";
    for (auto it = std::counted_iterator{std::cbegin(v), size};
         it != std::default_sentinel; ++it) {
        std::cout << *it << ", ";
    std::cout << "}\n";
int main() {
    const auto src = {"Arcturus"s, "Betelgeuse"s, "Canopus"s, "Deneb"s, "Elnath"s };
    print("src", src);
    std::vector<decltype(src)::value_type> dst;
    std::ranges::copy(std::counted_iterator{src.begin(), 3},
    print("dst", dst);


src[5] { Arcturus, Betelgeuse, Canopus, Deneb, Elnath, }
dst[3] { Arcturus, Betelgeuse, Canopus, }

[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
P2259R1 C++20 member typedefs are not provided
std::incrementable_traits is specialized for counted_iterator
member typedefs are added to account for iterator_traits fix
redundant std::incrementable_traits specialization is removed

[edit] See also

default sentinel for use with iterators that know the bound of their range
(class) [edit]
creates a subrange from an iterator and a count
(customization point object) [edit]
a view consisting of the first N elements of another view
(class template) (range adaptor object) [edit]