std::common_iterator

From cppreference.com
< cpp‎ | iterator
 
 
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
Utilities
(C++20)
Iterator adaptors
Stream iterators
Iterator customization points
Iterator operations
(C++11)
(C++11)
Range access
(C++11)(C++14)
(C++11)(C++14)
(C++17)(C++20)
(C++14)(C++14)
(C++14)(C++14)
(C++17)
(C++17)
 
std::common_iterator
 
Defined in header <iterator>
template< std::input_or_output_iterator I, std::sentinel_for<I> S >

  requires ( !std::same_as<I, S> && std::copyable<I> )

    class common_iterator;
(since C++20)

std::common_iterator is an iterator I / sentinel S adaptor that may represent a non-common range (where the types of I and S differ) as a common_range, by containing either an iterator or a sentinel, and defining the appropriate equality comparison operators operator==.
std::common_iterator can be used as a "bridge" between sequences represented by iterator/sentinel pair and legacy functions that expect common_range-like sequences.

Member functions

constructs a new iterator adaptor
(public member function)
(C++20)
assigns another iterator adaptor
(public member function)
accesses the pointed-to element
(public member function)
advances the iterator adaptor
(public member function)

Member objects

Member name Definition
var (private) an object of type std::variant<I, S>, the name is for exposition only

Non-member functions

compares the underlying iterators or sentinels
(function template)
(C++20)
computes the distance between two iterator adaptors
(function template)
(C++20)
casts the result of dereferencing the underlying iterator to its associated rvalue reference type
(function)
(C++20)
swaps the objects pointed to by two underlying iterators
(function template)

Helper classes

computes the associated difference type of the std::common_iterator type
(class template specialization)
provides uniform interface to the properties of the std::common_iterator type
(class template specialization)

Example

#include <algorithm>
#include <list>
#include <iostream>
#include <iterator>
#include <string>
 
template <class ForwardIter>
void fire(ForwardIter first, ForwardIter last) {
    std::copy(first, last, std::ostream_iterator<std::string>{std::cout, " "});    
}
 
int main() {
    std::list<std::string> stars{"Pollux", "Arcturus", "Mira", "Aldebaran", "Sun"};
    using IT = std::common_iterator<
                   std::counted_iterator<std::list<std::string>::iterator>,
                   std::default_sentinel_t>;
    fire( IT(std::counted_iterator(stars.begin(), stars.size()-1)),
          IT(std::default_sentinel) );
}

Output:

Pollux Arcturus Mira Aldebaran

References

  • C++20 standard (ISO/IEC 14882:2020):
  • 23.5.4 Common iterators [iterators.common]

See also

specifies that a range has identical iterator and sentinel types
(concept)
converts a view into a common_range
(class template) (range adaptor object)