NAME¶

std::common_iterator - std::common_iterator

Synopsis¶

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> ) (since C++20)

class common_iterator;

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¶

constructor constructs a new iterator adaptor
(C++20) (public member function)
operator= assigns another iterator adaptor
(C++20) (public member function)
operator* accesses the pointed-to element
operator-> (public member function)
(C++20)
operator++ advances the iterator adaptor
operator++(int) (public member function)
(C++20)

Non-member functions¶

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

Helper classes¶

computes the associated difference
std::incrementable_traits<std::common_iterator> type of the std::common_iterator
(C++20) type
(class template specialization)

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

Example¶

// Run this code

#include <algorithm>
#include <iostream>
#include <iterator>
#include <list>
#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++23 standard (ISO/IEC 14882:2023):

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

* 23.5.4 Common iterators [iterators.common]

See also¶

ranges::common_range specifies that a range has identical iterator and sentinel
(C++20) types
(concept)
ranges::common_view converts a view into a common_range
views::common (class template) (range adaptor object)
(C++20)