< cpp‎ | iterator
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
Iterator adaptors

Iterator customization points
Iterator operations
Range access
Defined in header <iterator>
template< std::input_iterator Iter >
class basic_const_iterator;
(since C++23)

std::basic_const_iterator is an iterator adaptor which behaves exactly like the underlying iterator (which must be at least an LegacyInputIterator or model input_iterator), except that dereferencing converts the value returned by the underlying iterator as immutable. Specializations of std::basic_const_iterator are constant iterators, that is, the iterator can never be used as an output iterator because modifying elements is not allowed.


[edit] Member types

Member type Definition

If Iter models forward_iterator:

Otherwise, there is no member iterator_category.

value_type std::iter_value_t<Iter>
difference_type std::iter_difference_t<Iter>
reference (private) std::iter_const_reference_t<Iter>
(exposition-only member type*)

[edit] Member objects

Member name Definition
current (private) the underlying iterator from which base() copies or moves
(exposition-only member object*)

[edit] Member functions

constructs a new iterator adaptor
(public member function) [edit]
accesses the underlying iterator
(public member function) [edit]
accesses the pointed-to element
(public member function) [edit]
accesses an element by index
(public member function) [edit]
advances or decrements the iterator
(public member function) [edit]
converts into any constant iterator to which an underlying iterator can be convertible
(public member function) [edit]
compares the underlying iterators
(public member function) [edit]

[edit] Non-member functions

compares basic_const_iterator with non-basic_const_iterator
(function template) [edit]
advances or decrements the iterator
(function template) [edit]
computes the distance between two iterator adaptors
(function template) [edit]
casts the result of dereferencing the underlying iterator to its associated rvalue reference type
(function) [edit]

[edit] Helper classes

determines the common type of an iterator and an adapted basic_const_iterator type
(class template specialization) [edit]

[edit] Helper alias templates

template< std::input_iterator I >
using const_iterator = /* see description */;
(since C++23)

If I models constant-iterator (an exposition-only concept), then const_iterator<I> denotes a type I. Otherwise, basic_const_iterator<I>.

template< std::semiregular S >
using const_sentinel = /* see description */;
(since C++23)

If S models input_iterator, then const_sentinel<S> denotes a type const_iterator<S>. Otherwise, S.

[edit] Helper function templates

template< std::input_iterator T >
constexpr const_iterator<T> make_const_iterator( I it ) { return it; }
(since C++23)
template< std::semiregular S >
constexpr const_sentinel<S> make_const_sentinel( S s ) { return s; }
(since C++23)

[edit] Notes

Feature-test macro Value Std Feature
__cpp_lib_ranges_as_const 202207L (C++23) std::basic_const_iterator
202311L (C++23)
std::basic_const_iterator should follow its underlying type's convertibility

[edit] Example

#include <cassert>
#include <iterator>
#include <vector>
int main()
    std::vector v{1, 2, 3};
    std::vector<int>::iterator i = v.begin();
    *i = 4;   // OK
    i[1] = 4; // OK, the same as *(i + 1) = 4;
    auto ci = std::make_const_iterator(i);
    assert(*ci == 4);   // OK, can read the underlying object
    assert(ci[0] == 4); // OK, ditto
    // *ci = 13;        // Error: location is read-only
    ci.base()[0] = 42;  // OK, underlying iterator is writable

[edit] Defect reports

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

DR Applied to Behavior as published Correct behavior
P2836R1 C++23 basic_const_iterator doesn't follow its underlying type's convertibility conversion operator provided