home | help 
std::basic_const_iterator(3)   C++ Standard Libary  std::basic_const_iterator(3)

NAME
     std::basic_const_iterator - std::basic_const_iterator

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::ba-
     sic_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
	Member type	    Definition
			    If Iter models forward_iterator:

	iterator_category     * member iterator_category is the same type as
				std::iterator_traits<Iter>::iterator_category.

			    Otherwise, there is no member iterator_category.
			      * std::contiguous_iterator_tag, if Iter models
				contiguous_iterator;
			      * std::random_access_iterator_tag, if Iter models
	iterator_concept	random_access_iterator;
			      * std::bidirectional_iterator_tag, if Iter models
				bidirectional_iterator;
			      *  std::forward_iterator_tag,  if Iter models for-
     ward_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
	Member name	  Definition
	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
	operator->		   (public member function)
	operator[]		   accesses an element by index
				   (public member function)
	operator++
	operator++(int)
	operator+=		   advances or decrements the iterator
	operator--		   (public member function)
	operator--(int)
	operator-=
				   converts  into any constant iterator to which
     an
	operator constant-iterator underlying iterator can be convertible
				   (public member function)
	operator==
	operator<
	operator>		   compares the underlying iterators
	operator<=		   (public member function)
	operator>=
	operator<=>

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

Helper classes
						    determines the  common  type
     of an
	std::common_type<std::basic_const_iterator> iterator and an adapted
	(C++23) 				    basic_const_iterator type
						    (class  template specializa-
     tion)

	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 >
	constexpr const_iterator<T> make_const_iterator( I it  )  {  return  it;
     (since C++23)
	}
	template<		std::semiregular	       S	       >
     (since C++23)
	constexpr const_sentinel<S> make_const_sentinel( S s ) { return s; }

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

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 retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to	       Behavior as  published		    Cor-
     rect behavior
	P2836R1 C++23	   basic_const_iterator doesn't follow its	 conver-
     sion operator
			   underlying  type's  convertibility		    pro-
     vided

http://cppreference.com 	   2024.06.10	    std::basic_const_iterator(3)
home | help