Add missing C++ STL iterator declarations and correct their const/non-const behaviour. (GH-4528)

The current implementation of iterators had the following bugs:

- it was possible to assign `const_iterator` to `iterator`
- it was not possible to assign `iterator` to `const_iterator`
- operator* did not always return `value_type` e.g. for
  `const_iterator` this often returned `T&` instead of
  `const value_type&`
- increment operators always returned `iterators`. This caused
  e.g. `const_iterator + 1` to result in a `iterator` instead of
  a `const_iterator`
- comparision operators could not be used to compare
  `iterators` and `const_iterators` (`const_iterator == iterator`)

Cython/Includes/libcpp/deque.pxd

@@ -9,36 +9,109 @@ cdef extern from "<deque>" namespace "std" nogil:
         ctypedef size_t size_type
         ctypedef ptrdiff_t difference_type
 
+        cppclass const_iterator
         cppclass iterator:
-            T& operator*()
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
             iterator operator++()
             iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
             iterator operator+(size_type)
             iterator operator-(size_type)
             difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
             bint operator==(iterator)
+            bint operator==(const_iterator)
             bint operator!=(iterator)
+            bint operator!=(const_iterator)
             bint operator<(iterator)
+            bint operator<(const_iterator)
             bint operator>(iterator)
+            bint operator>(const_iterator)
             bint operator<=(iterator)
+            bint operator<=(const_iterator)
             bint operator>=(iterator)
+            bint operator>=(const_iterator)
+        cppclass const_iterator:
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            const_iterator operator+(size_type)
+            const_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+            bint operator<(iterator)
+            bint operator<(const_iterator)
+            bint operator>(iterator)
+            bint operator>(const_iterator)
+            bint operator<=(iterator)
+            bint operator<=(const_iterator)
+            bint operator>=(iterator)
+            bint operator>=(const_iterator)
+
+        cppclass const_reverse_iterator
         cppclass reverse_iterator:
-            T& operator*()
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
             reverse_iterator operator++()
             reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
             reverse_iterator operator+(size_type)
             reverse_iterator operator-(size_type)
-            difference_type operator-(reverse_iterator)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
             bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
             bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
             bint operator<(reverse_iterator)
+            bint operator<(const_reverse_iterator)
             bint operator>(reverse_iterator)
+            bint operator>(const_reverse_iterator)
             bint operator<=(reverse_iterator)
+            bint operator<=(const_reverse_iterator)
             bint operator>=(reverse_iterator)
-        cppclass const_iterator(iterator):
-            pass
-        cppclass const_reverse_iterator(reverse_iterator):
-            pass
+            bint operator>=(const_reverse_iterator)
+        cppclass const_reverse_iterator:
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            const_reverse_iterator operator+(size_type)
+            const_reverse_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+            bint operator<(reverse_iterator)
+            bint operator<(const_reverse_iterator)
+            bint operator>(reverse_iterator)
+            bint operator>(const_reverse_iterator)
+            bint operator<=(reverse_iterator)
+            bint operator<=(const_reverse_iterator)
+            bint operator>=(reverse_iterator)
+            bint operator>=(const_reverse_iterator)
+
         deque() except +
         deque(deque&) except +
         deque(size_t) except +

Cython/Includes/libcpp/forward_list.pxd

@@ -14,6 +14,7 @@ cdef extern from "<forward_list>" namespace "std" nogil:
             iterator(iterator &)
             T& operator*()
             iterator operator++()
+            iterator operator++(int)
             bint operator==(iterator)
             bint operator!=(iterator)
         cppclass const_iterator(iterator):

Cython/Includes/libcpp/list.pxd

@@ -9,26 +9,61 @@ cdef extern from "<list>" namespace "std" nogil:
         ctypedef size_t size_type
         ctypedef ptrdiff_t difference_type
 
+        cppclass const_iterator
         cppclass iterator:
-            iterator()
-            iterator(iterator &)
-            T& operator*()
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
             iterator operator++()
             iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
             bint operator==(iterator)
+            bint operator==(const_iterator)
             bint operator!=(iterator)
+            bint operator!=(const_iterator)
+        cppclass const_iterator:
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
+        cppclass const_reverse_iterator
         cppclass reverse_iterator:
-            reverse_iterator()
-            reverse_iterator(iterator &)
-            T& operator*()
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
             reverse_iterator operator++()
             reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
             bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
             bint operator!=(reverse_iterator)
-        cppclass const_iterator(iterator):
-            pass
-        cppclass const_reverse_iterator(reverse_iterator):
-            pass
+            bint operator!=(const_reverse_iterator)
+        cppclass const_reverse_iterator:
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+    
         list() except +
         list(list&) except +
         list(size_t, T&) except +

Cython/Includes/libcpp/map.pxd

@@ -7,32 +7,72 @@ cdef extern from "<map>" namespace "std" nogil:
         ctypedef pair[const T, U] value_type
         ctypedef COMPARE key_compare
         ctypedef ALLOCATOR allocator_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
+            iterator() except +
+            iterator(iterator&) except +
+            # correct would be value_type& but this does not work
+            # well with cython's code gen
             pair[T, U]& operator*()
-            iterator& operator++()
-            iterator& operator--()
-            bint operator==(const iterator&)
-            bint operator!=(const iterator&)
-        cppclass reverse_iterator:
-            pair[T, U]& operator*()
-            reverse_iterator& operator++()
-            reverse_iterator& operator--()
-            bint operator==(const reverse_iterator&)
-            bint operator!=(const reverse_iterator&)
+            iterator operator++()
+            iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            # correct would be const value_type& but this does not work
+            # well with cython's code gen
             const pair[T, U]& operator*()
-            const_iterator& operator++()
-            const_iterator& operator--()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
+        cppclass const_reverse_iterator
+        cppclass reverse_iterator:
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
+            reverse_iterator operator++()
+            reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
         cppclass const_reverse_iterator:
-            const_reverse_iterator(reverse_iterator)
-            const pair[T, U]& operator*()
-            const_reverse_iterator& operator++()
-            const_reverse_iterator& operator--()
-            bint operator==(const const_reverse_iterator&)
-            bint operator!=(const const_reverse_iterator&)
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+
         map() except +
         map(map&) except +
         #map(key_compare&)
@@ -88,32 +128,72 @@ cdef extern from "<map>" namespace "std" nogil:
         ctypedef pair[const T, U] value_type
         ctypedef COMPARE key_compare
         ctypedef ALLOCATOR allocator_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
+            iterator() except +
+            iterator(iterator&) except +
+            # correct would be value_type& but this does not work
+            # well with cython's code gen
             pair[T, U]& operator*()
-            iterator& operator++()
-            iterator& operator--()
-            bint operator==(const iterator&)
-            bint operator!=(const iterator&)
-        cppclass reverse_iterator:
-            pair[T, U]& operator*()
-            reverse_iterator& operator++()
-            reverse_iterator& operator--()
-            bint operator==(const reverse_iterator&)
-            bint operator!=(const reverse_iterator&)
+            iterator operator++()
+            iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            # correct would be const value_type& but this does not work
+            # well with cython's code gen
             const pair[T, U]& operator*()
-            const_iterator& operator++()
-            const_iterator& operator--()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
+        cppclass const_reverse_iterator
+        cppclass reverse_iterator:
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
+            reverse_iterator operator++()
+            reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
         cppclass const_reverse_iterator:
-            const_reverse_iterator(reverse_iterator)
-            const pair[T, U]& operator*()
-            const_reverse_iterator& operator++()
-            const_reverse_iterator& operator--()
-            bint operator==(const const_reverse_iterator&)
-            bint operator!=(const const_reverse_iterator&)
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+
         multimap() except +
         multimap(const multimap&) except +
         #multimap(key_compare&)

Cython/Includes/libcpp/set.pxd

@@ -3,32 +3,68 @@ from .utility cimport pair
 cdef extern from "<set>" namespace "std" nogil:
     cdef cppclass set[T]:
         ctypedef T value_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
-            T& operator*()
-            iterator& operator++()
-            iterator& operator--()
-            bint operator==(const iterator &)
-            bint operator!=(const iterator &)
-        cppclass reverse_iterator:
-            T& operator*()
-            reverse_iterator& operator++()
-            reverse_iterator& operator--()
-            bint operator==(const reverse_iterator&)
-            bint operator!=(const reverse_iterator&)
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
+            iterator operator++()
+            iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
-            const T& operator*()
-            const_iterator& operator++()
-            const_iterator& operator--()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
+        cppclass const_reverse_iterator
+        cppclass reverse_iterator:
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
+            reverse_iterator operator++()
+            reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
         cppclass const_reverse_iterator:
-            const_reverse_iterator(reverse_iterator)
-            const T& operator*()
-            const_reverse_iterator& operator++()
-            const_reverse_iterator& operator--()
-            bint operator==(const const_reverse_iterator&)
-            bint operator!=(const const_reverse_iterator&)
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+    
         set() except +
         set(set&) except +
         #set(key_compare&)
@@ -58,6 +94,7 @@ cdef extern from "<set>" namespace "std" nogil:
         const_iterator const_find "find"(const T&)
         pair[iterator, bint] insert(const T&) except +
         iterator insert(iterator, const T&) except +
+        iterator insert(const_iterator, const T&) except +
         iterator const_insert "insert"(const_iterator, const T&) except +
         void insert[InputIt](InputIt, InputIt) except +
         #key_compare key_comp()
@@ -79,32 +116,66 @@ cdef extern from "<set>" namespace "std" nogil:
     cdef cppclass multiset[T]:
         ctypedef T value_type
 
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
-            T& operator*()
-            iterator& operator++()
-            iterator& operator--()
-            bint operator==(const iterator&)
-            bint operator!=(const iterator&)
-        cppclass reverse_iterator:
-            T& operator*()
-            reverse_iterator& operator++()
-            reverse_iterator& operator--()
-            bint operator==(const reverse_iterator&)
-            bint operator!=(const reverse_iterator&)
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
+            iterator operator++()
+            iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
-            const T& operator*()
-            const_iterator& operator++()
-            const_iterator& operator--()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
+        cppclass const_reverse_iterator
+        cppclass reverse_iterator:
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
+            reverse_iterator operator++()
+            reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
         cppclass const_reverse_iterator:
-            const_reverse_iterator(reverse_iterator)
-            const T& operator*()
-            const_reverse_iterator& operator++()
-            const_reverse_iterator& operator--()
-            bint operator==(const const_reverse_iterator&)
-            bint operator!=(const const_reverse_iterator&)
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
 
         multiset() except +
         multiset(multiset&) except +

Cython/Includes/libcpp/string.pxd

@@ -7,34 +7,116 @@ cdef extern from "<string>" namespace "std::string" nogil:
 
 cdef extern from "<string>" namespace "std" nogil:
     cdef cppclass string:
+        ctypedef char value_type
 
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
-            iterator()
-            char& operator*()
-            iterator(iterator&)
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
             iterator operator++()
             iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            iterator operator+(size_type)
+            iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
             bint operator==(iterator)
+            bint operator==(const_iterator)
             bint operator!=(iterator)
-
+            bint operator!=(const_iterator)
+            bint operator<(iterator)
+            bint operator<(const_iterator)
+            bint operator>(iterator)
+            bint operator>(const_iterator)
+            bint operator<=(iterator)
+            bint operator<=(const_iterator)
+            bint operator>=(iterator)
+            bint operator>=(const_iterator)
+        cppclass const_iterator:
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            const_iterator operator+(size_type)
+            const_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+            bint operator<(iterator)
+            bint operator<(const_iterator)
+            bint operator>(iterator)
+            bint operator>(const_iterator)
+            bint operator<=(iterator)
+            bint operator<=(const_iterator)
+            bint operator>=(iterator)
+            bint operator>=(const_iterator)
+
+        cppclass const_reverse_iterator
         cppclass reverse_iterator:
-            char& operator*()
-            iterator operator++()
-            iterator operator--()
-            iterator operator+(size_t)
-            iterator operator-(size_t)
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
+            value_type& operator*()
+            reverse_iterator operator++()
+            reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
+            reverse_iterator operator+(size_type)
+            reverse_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
             bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
             bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
             bint operator<(reverse_iterator)
+            bint operator<(const_reverse_iterator)
             bint operator>(reverse_iterator)
+            bint operator>(const_reverse_iterator)
             bint operator<=(reverse_iterator)
+            bint operator<=(const_reverse_iterator)
             bint operator>=(reverse_iterator)
-
-        cppclass const_iterator(iterator):
-            pass
-
-        cppclass const_reverse_iterator(reverse_iterator):
-            pass
+            bint operator>=(const_reverse_iterator)
+        cppclass const_reverse_iterator:
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const value_type& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            const_reverse_iterator operator+(size_type)
+            const_reverse_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+            bint operator<(reverse_iterator)
+            bint operator<(const_reverse_iterator)
+            bint operator>(reverse_iterator)
+            bint operator>(const_reverse_iterator)
+            bint operator<=(reverse_iterator)
+            bint operator<=(const_reverse_iterator)
+            bint operator>=(reverse_iterator)
+            bint operator>=(const_reverse_iterator)
 
         string() except +
         string(const string& s) except +

Cython/Includes/libcpp/unordered_map.pxd

@@ -6,17 +6,44 @@ cdef extern from "<unordered_map>" namespace "std" nogil:
         ctypedef U mapped_type
         ctypedef pair[const T, U] value_type
         ctypedef ALLOCATOR allocator_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass iterator
         cppclass iterator:
+            iterator() except +
+            iterator(iterator&) except +
+            # correct would be value_type& but this does not work
+            # well with cython's code gen
             pair[T, U]& operator*()
-            iterator& operator++()
-            bint operator==(const iterator&)
-            bint operator!=(const iterator&)
+            iterator operator++()
+            iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            operator=(iterator&) except +
+            # correct would be const value_type& but this does not work
+            # well with cython's code gen
             const pair[T, U]& operator*()
-            const_iterator& operator++()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
         unordered_map() except +
         unordered_map(unordered_map&) except +
         #unordered_map(key_compare&)
@@ -74,17 +101,40 @@ cdef extern from "<unordered_map>" namespace "std" nogil:
         ctypedef U mapped_type
         ctypedef pair[const T, U] value_type
         ctypedef ALLOCATOR allocator_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
+            iterator() except +
+            iterator(iterator&) except +
+            # correct would be value_type& but this does not work
+            # well with cython's code gen
             pair[T, U]& operator*()
             iterator operator++()
+            iterator operator++(int)
             bint operator==(iterator)
+            bint operator==(const_iterator)
             bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            operator=(iterator&) except +
+            # correct would be const value_type& but this does not work
+            # well with cython's code gen
             const pair[T, U]& operator*()
-            const_iterator& operator++()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator operator++()
+            const_iterator operator++(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
         unordered_multimap() except +
         unordered_multimap(const unordered_multimap&) except +
         #unordered_multimap(key_compare&)

Cython/Includes/libcpp/unordered_set.pxd

@@ -3,17 +3,40 @@ from .utility cimport pair
 cdef extern from "<unordered_set>" namespace "std" nogil:
     cdef cppclass unordered_set[T,HASH=*,PRED=*,ALLOCATOR=*]:
         ctypedef T value_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
-            T& operator*()
-            iterator& operator++()
-            bint operator==(const iterator&)
-            bint operator!=(const iterator&)
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
+            iterator operator++()
+            iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
-            const T& operator*()
-            const_iterator& operator++()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+
         unordered_set() except +
         unordered_set(unordered_set&) except +
         #unordered_set& operator=(unordered_set&)
@@ -56,17 +79,34 @@ cdef extern from "<unordered_set>" namespace "std" nogil:
     cdef cppclass unordered_multiset[T,HASH=*,PRED=*,ALLOCATOR=*]:
         ctypedef T value_type
 
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass const_iterator
         cppclass iterator:
-            T& operator*()
-            iterator& operator++()
-            bint operator==(const iterator&)
-            bint operator!=(const iterator&)
+            iterator() except +
+            iterator(iterator&) except +
+            value_type& operator*()
+            iterator operator++()
+            iterator operator++(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
         cppclass const_iterator:
-            const_iterator(iterator)
-            const T& operator*()
-            const_iterator& operator++()
-            bint operator==(const const_iterator&)
-            bint operator!=(const const_iterator&)
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            operator=(iterator&) except +
+            const value_type& operator*()
+            const_iterator operator++()
+            const_iterator operator++(int)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
 
         unordered_multiset() except +
         unordered_multiset(unordered_multiset&) except +

Cython/Includes/libcpp/vector.pxd

@@ -9,36 +9,109 @@ cdef extern from "<vector>" namespace "std" nogil:
         ctypedef size_t size_type
         ctypedef ptrdiff_t difference_type
 
+        cppclass const_iterator
         cppclass iterator:
+            iterator() except +
+            iterator(iterator&) except +
             T& operator*()
             iterator operator++()
             iterator operator--()
+            iterator operator++(int)
+            iterator operator--(int)
             iterator operator+(size_type)
             iterator operator-(size_type)
             difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
             bint operator==(iterator)
+            bint operator==(const_iterator)
             bint operator!=(iterator)
+            bint operator!=(const_iterator)
             bint operator<(iterator)
+            bint operator<(const_iterator)
             bint operator>(iterator)
+            bint operator>(const_iterator)
             bint operator<=(iterator)
+            bint operator<=(const_iterator)
             bint operator>=(iterator)
+            bint operator>=(const_iterator)
+        cppclass const_iterator:
+            const_iterator() except +
+            const_iterator(iterator&) except +
+            const_iterator(const_iterator&) except +
+            operator=(iterator&) except +
+            const T& operator*()
+            const_iterator operator++()
+            const_iterator operator--()
+            const_iterator operator++(int)
+            const_iterator operator--(int)
+            const_iterator operator+(size_type)
+            const_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
+            bint operator==(iterator)
+            bint operator==(const_iterator)
+            bint operator!=(iterator)
+            bint operator!=(const_iterator)
+            bint operator<(iterator)
+            bint operator<(const_iterator)
+            bint operator>(iterator)
+            bint operator>(const_iterator)
+            bint operator<=(iterator)
+            bint operator<=(const_iterator)
+            bint operator>=(iterator)
+            bint operator>=(const_iterator)
+
+        cppclass const_reverse_iterator
         cppclass reverse_iterator:
+            reverse_iterator() except +
+            reverse_iterator(reverse_iterator&) except +
             T& operator*()
             reverse_iterator operator++()
             reverse_iterator operator--()
+            reverse_iterator operator++(int)
+            reverse_iterator operator--(int)
             reverse_iterator operator+(size_type)
             reverse_iterator operator-(size_type)
-            difference_type operator-(reverse_iterator)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
             bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
             bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
             bint operator<(reverse_iterator)
+            bint operator<(const_reverse_iterator)
             bint operator>(reverse_iterator)
+            bint operator>(const_reverse_iterator)
             bint operator<=(reverse_iterator)
+            bint operator<=(const_reverse_iterator)
             bint operator>=(reverse_iterator)
-        cppclass const_iterator(iterator):
-            pass
-        cppclass const_reverse_iterator(reverse_iterator):
-            pass
+            bint operator>=(const_reverse_iterator)
+        cppclass const_reverse_iterator:
+            const_reverse_iterator() except +
+            const_reverse_iterator(reverse_iterator&) except +
+            operator=(reverse_iterator&) except +
+            const T& operator*()
+            const_reverse_iterator operator++()
+            const_reverse_iterator operator--()
+            const_reverse_iterator operator++(int)
+            const_reverse_iterator operator--(int)
+            const_reverse_iterator operator+(size_type)
+            const_reverse_iterator operator-(size_type)
+            difference_type operator-(iterator)
+            difference_type operator-(const_iterator)
+            bint operator==(reverse_iterator)
+            bint operator==(const_reverse_iterator)
+            bint operator!=(reverse_iterator)
+            bint operator!=(const_reverse_iterator)
+            bint operator<(reverse_iterator)
+            bint operator<(const_reverse_iterator)
+            bint operator>(reverse_iterator)
+            bint operator>(const_reverse_iterator)
+            bint operator<=(reverse_iterator)
+            bint operator<=(const_reverse_iterator)
+            bint operator>=(reverse_iterator)
+            bint operator>=(const_reverse_iterator)
+
         vector() except +
         vector(vector&) except +
         vector(size_type) except +

tests/errors/cpp_no_const_iterator_conversion.pyx

+# mode: error
+# tag: cpp
+
+from libcpp.deque cimport deque
+from libcpp.list cimport list
+from libcpp.map cimport map
+from libcpp.set cimport set
+from libcpp.string cimport string
+from libcpp.unordered_map cimport unordered_map
+from libcpp.unordered_set cimport unordered_set
+from libcpp.vector cimport vector
+
+def deque_iterator():
+    cdef deque[int].iterator begin
+    cdef deque[int].const_iterator cbegin = begin
+    begin = cbegin
+
+def list_iterator():
+    cdef list[int].iterator begin
+    cdef list[int].const_iterator cbegin = begin
+    begin = cbegin
+
+def map_iterator():
+    cdef map[int, int].iterator begin
+    cdef map[int, int].const_iterator cbegin = begin
+    begin = cbegin
+
+def set_iterator():
+    cdef set[int].iterator begin
+    cdef set[int].const_iterator cbegin = begin
+    begin = cbegin
+
+def string_iterator():
+    cdef string.iterator begin
+    cdef string.const_iterator cbegin = begin
+    begin = cbegin
+
+def map_iterator():
+    cdef unordered_map[int, int].iterator begin
+    cdef unordered_map[int, int].const_iterator cbegin = begin
+    begin = cbegin
+
+def set_iterator():
+    cdef unordered_set[int].iterator begin
+    cdef unordered_set[int].const_iterator cbegin = begin
+    begin = cbegin
+
+def vector_iterator():
+    cdef vector[int].iterator begin
+    cdef vector[int].const_iterator cbegin = begin
+    begin = cbegin
+
+_ERRORS = u"""
+16:12: Cannot assign type 'const_iterator' to 'iterator'
+21:12: Cannot assign type 'const_iterator' to 'iterator'
+26:12: Cannot assign type 'const_iterator' to 'iterator'
+31:12: Cannot assign type 'const_iterator' to 'iterator'
+36:12: Cannot assign type 'const_iterator' to 'iterator'
+41:12: Cannot assign type 'const_iterator' to 'iterator'
+46:12: Cannot assign type 'const_iterator' to 'iterator'
+51:12: Cannot assign type 'const_iterator' to 'iterator'
+"""

tests/run/cpp_iterators.pyx

@@ -177,3 +177,27 @@ def test_iteration_from_function_call():
         print(i)
     for i in make_vec3():
         print(i)
+
+def test_const_iterator_calculations(py_v):
+    """
+    >>> print(test_const_iterator_calculations([1, 2, 3]))
+    [3, 3, 3, 3, True, True, False, False]
+    """
+    cdef deque[int] dint
+    for i in py_v:
+        dint.push_back(i)
+    cdef deque[int].iterator first = dint.begin()
+    cdef deque[int].iterator last = dint.end()
+    cdef deque[int].const_iterator cfirst = first
+    cdef deque[int].const_iterator clast = last
+
+    return [
+        last - first,
+        last - cfirst,
+        clast - first,
+        clast - cfirst,
+        first == cfirst,
+        last == clast,
+        first == clast,
+        last == cfirst
+    ]

tests/run/cpp_stl_map.pyx

@@ -159,3 +159,17 @@ def test_unordered_map_find_erase(vals, to_remove):
     it = um.find(to_remove)
     it = um.erase(it)
     return sorted([ item for item in um ])
+
+def test_iterator_stack_allocated():
+    """
+    https://github.com/cython/cython/issues/4657 - mainly a compile test showing
+    that const iterators can be stack allocated
+    >>> test_iterator_stack_allocated()
+    """
+    cdef map[int,int] mymap = map[int,int]()
+    cdef unordered_map[int,int] myumap = unordered_map[int,int]()
+    cdef int ckey = 5
+    it = mymap.const_find(ckey)
+    assert it == mymap.const_end()
+    uit = myumap.const_find(ckey)
+    assert uit == myumap.const_end()

tests/run/cpp_stl_set.pyx

@@ -159,3 +159,17 @@ def test_unordered_set_find_erase(vals, to_remove):
     it = us.find(to_remove)
     it = us.erase(it)
     return sorted([item for item in us])
+
+def test_iterator_stack_allocated():
+    """
+    https://github.com/cython/cython/issues/4657 - mainly a compile test showing
+    that const iterators can be stack allocated
+    >>> test_iterator_stack_allocated()
+    """
+    cdef set[int] myset = set[int]()
+    cdef unordered_set[int] myuset = unordered_set[int]()
+    cdef int ckey = 5
+    it = myset.const_find(ckey)
+    assert it == myset.const_end()
+    uit = myuset.const_find(ckey)
+    assert uit == myuset.const_end()