std::basic_const_iterator(3)

💅 std::basic_const_iterator 💅

okay bestie, welcome to the <iterator> page for std::basic_const_iterator, aka std::basic_const_iterator(3) in the C++ Standard Libary manual. this one is literally an icon 🎀

---

✨ NAME ✨

• std::basic_const_iterator — std::basic_const_iterator (yes that’s the whole name, main character energy only)

🌸 Synopsis 🌸

Defined in header <iterator>.

template< std::input_iterator Iter >  (since C++23)
class basic_const_iterator;

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. 🫶

🎀 Member types 🎀

• iterator_category
  • If Iter models forward_iterator: member iterator_category is the same type as std::iterator_traits<Iter>::iterator_category.
  • Otherwise, there is no member iterator_category.
• iterator_concept
  • std::contiguous_iterator_tag, if Iter models contiguous_iterator;
  • std::random_access_iterator_tag, if Iter models random_access_iterator;
  • std::bidirectional_iterator_tag, if Iter models bidirectional_iterator;
  • std::forward_iterator_tag, if Iter models forward_iterator;
  • std::input_iterator_tag otherwise.
• 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*)

🦋 Member objects 🦋

• current (private) — the underlying iterator from which base() copies or moves (exposition-only member object*)

💖 Member functions 💖

• constructor — constructs a new iterator adaptor (public member function)
• base — accesses the underlying iterator (public member function)
• operator* — accesses the pointed-to element (public member function)
• operator-> — accesses the pointed-to element (public member function)
• operator[] — accesses an element by index (public member function)
• operator++ — advances or decrements the iterator (public member function)
• operator++(int) — advances or decrements the iterator (public member function)
• operator+= — advances or decrements the iterator (public member function)
• operator-- — advances or decrements the iterator (public member function)
• operator--(int) — advances or decrements the iterator (public member function)
• operator-= — advances or decrements the iterator (public member function)
• operator constant-iterator — converts into any constant iterator to which an underlying iterator can be convertible (public member function)
• operator== — compares the underlying iterators (public member function)
• operator< — compares the underlying iterators (public member function)
• operator> — compares the underlying iterators (public member function)
• operator<= — compares the underlying iterators (public member function)
• operator>= — compares the underlying iterators (public member function)
• operator<=> — compares the underlying iterators (public member function)

🧚 Non-member functions 🧚

• operator<, operator>, operator<=, operator>=, operator<=> — compares basic_const_iterator with non-basic_const_iterator (function template) (C++23)
• operator+, operator- — advances or decrements the iterator (function template) (C++23)
• operator- — computes the distance between two iterator adaptors (function template) (C++23)
• iter_move — casts the result of dereferencing the underlying iterator to its associated rvalue reference type (function) (C++23)

👑 Helper classes 👑

• std::common_type<std::basic_const_iterator> — determines the common type of an iterator and an adapted basic_const_iterator type (class template specialization) (C++23)

🌈 Helper alias templates 🌈

template< std::input_iterator I > (since C++23)

using const_iterator = /* see description */;

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

using const_sentinel = /* see description */;

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

⭐ Helper function templates ⭐

template< std::input_iterator T > (since C++23)

constexpr const_iterator<T> make_const_iterator( I it ) { return it; }

template< std::semiregular S > (since C++23)

constexpr const_sentinel<S> make_const_sentinel( S s ) { return s; }

🔥 Notes 🔥

• __cpp_lib_ranges_as_const — value 202207L, std (C++23), feature std::basic_const_iterator
• __cpp_lib_ranges_as_const — value 202311L, std (C++23) (DR), feature std::basic_const_iterator should follow its underlying type's convertibility

🍓 Example 🍓

// Run this code

#include <cassert>
#include <iterator>
#include <vector>

int main()
{
    std::vector v{1, 2, 3};
    std::vector<int>::iterator i = v.begin();
    *i = 4;   // OK, v[0] == 4 now
    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[0] = 13;      // Error: ditto
    ci.base()[0] = 42;  // OK, underlying iterator is writable
    assert(*ci == 42);  // OK, underlying location v[0] was modified
}

💀 Defect reports 💀

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

• P2836R1 — applied to C++23; behavior as published: basic_const_iterator doesn't follow its underlying type's convertibility; correct behavior: conversion operator provided.

---

💖 source/version/date moment: this one’s from http://cppreference.com, dated 2024.06.10, and it’s the std::basic_const_iterator(3) page — mwah, periodt. 💖