std::counted_iterator - cppreference.com

From cppreference.com


`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_t if and only if its count reaches zero.

Member types

Member type	Definition
`iterator_type`	`I`
`value_type` (conditionally present)	`std::iter_value_t<I>` if `I` models `indirectly_readable`; otherwise, not defined
`difference_type`	`std::iter_difference_t<I>`
`iterator_concept` (conditionally present)	`I::iterator_concept` if present; otherwise, not defined
`iterator_category` (conditionally present)	`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*)
`length` (private)	the distance between the underlying iterator and the end of its range (exposition-only member object*)

Member functions

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

Non-member functions

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

Helper classes

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 << (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
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