std::counted_iterator(3)

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)