NAME¶

std::counted_iterator - std::counted_iterator

Synopsis¶

Defined in header <iterator>
template< std::input_or_output_iterator I > (since C++20)
class counted_iterator;

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.

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

Member objects¶

Member name Definition
current (private) the underlying iterator which base() accesses
(exposition-only member object*)
the distance between the underlying iterator and the end of its
length (private) range
(exposition-only member object*)

Member functions¶

constructor constructs a new iterator adaptor
(C++20) (public member function)
operator= assigns another iterator adaptor
(C++20) (public member function)
base accesses the underlying iterator
(C++20) (public member function)
count returns the distance to the end
(C++20) (public member function)
operator* accesses the pointed-to element
operator-> (public member function)
(C++20)
operator[] accesses an element by index
(C++20) (public member function)
operator++
operator++(int)
operator+=
operator+ advances or decrements the iterator
operator-- (public member function)
operator--(int)
operator-=
operator-
(C++20)

Non-member functions¶

operator== compares the distances to the end
operator<=> (function template)
(C++20)
operator==(std::default_sentinel) checks if the distance to the end is equal to 0
(C++20) (function template)
operator+ advances the iterator
(C++20) (function template)
operator- computes the distance between two iterator
(C++20) adaptors
(function template)
operator-(std::default_sentinel_t) computes the signed distance to the end
(C++20) (function template)
iter_move casts the result of dereferencing the underlying
(C++20) iterator to its associated rvalue reference type
(function)
iter_swap swaps the objects pointed to by two underlying
(C++20) iterators
(function template)

Helper classes¶

provides uniform interface to the
std::iterator_traits<std::counted_iterator> properties of the std::counted_iterator
(C++20) type
(class template specialization)

Example¶

// Run this code

#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 << (it.count() > 1 ? ", " : " ");
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},
std::default_sentinel,
std::back_inserter(dst));
print("dst", dst);
}

Output:¶

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

Defect reports

The following behavior-changing defect reports were applied retroactively to
previously published C++ standards.

DR Applied to Behavior as published Correct behavior
member typedefs are not provided member typedefs are added to
std::incrementable_traits account for iterator_traits fix
P2259R1 C++20 is specialized for redundant
counted_iterator std::incrementable_traits
specialization is removed

See also¶

default_sentinel_t default sentinel for use with iterators that know the bound of
(C++20) their range
(class)
views::counted creates a subrange from an iterator and a count
(C++20) (customization point object)
ranges::take_view a view consisting of the first N elements of another view
views::take (class template) (range adaptor object)
(C++20)