gh-35087: refactor: Use enum for face iterator status
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
### 📚 Description

Related to the feature request in #34773, I'm trying to make my own code
a bit more readable.

Here we replace the int representing the status of the face of the
iterator by an enumerator. This allows understanding this variable
without having to look up the meaning.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->

- [x] I have made sure that the title is self-explanatory and the
description concisely explains the PR.
- [x] I have linked an issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies
<!-- List all open pull requests that this PR logically depends on -->
<!--
- #xyz: short description why this is a dependency
- #abc: ...
-->
    
URL: #35087
Reported by: Jonathan Kliem
Reviewer(s): Jonathan Kliem, Matthias Köppe

Author: Release Manager

src/sage/geometry/polyhedron/combinatorial_polyhedron/combinatorial_face.pyx

@@ -70,7 +70,7 @@ import numbers
 from sage.rings.integer         cimport smallInteger
 from .conversions               cimport bit_rep_to_Vrep_list
 from .base                      cimport CombinatorialPolyhedron
-from .face_iterator             cimport FaceIterator_base
+from .face_iterator             cimport FaceIterator_base, FaceStatus
 from .polyhedron_face_lattice   cimport PolyhedronFaceLattice
 from .face_data_structure       cimport face_len_atoms, face_init, face_free, face_copy, face_issubset
 from .face_list_data_structure  cimport bit_rep_to_coatom_rep
@@ -177,7 +177,7 @@ cdef class CombinatorialFace(SageObject):
             self.atoms              = it.atoms
             self.coatoms            = it.coatoms
 
-            if it.structure.face_status == 0:
+            if it.structure.face_status == FaceStatus.NOT_INITIALIZED:
                 raise LookupError("face iterator not set to a face")
 
             face_init(self.face, self.coatoms.n_atoms(), self.coatoms.n_coatoms())

src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pxd

@@ -5,10 +5,16 @@ from .face_data_structure       cimport face_t
 from .face_list_data_structure  cimport face_list_t
 from .combinatorial_face        cimport CombinatorialFace
 
+cdef enum FaceStatus:
+    NOT_INITIALIZED
+    INITIALIZED
+    IGNORE_SUBSETS
+    ONLY_VISIT_SUBSETS
+
 cdef struct iter_s:
     bint dual                  # if 1, then iterate over dual Polyhedron
     face_t face                # the current face of the iterator
-    int face_status            # 0 not initialized, 1 initialized, 2 added to visited_all, 3 only visit subsets
+    FaceStatus face_status
     size_t *atom_rep           # a place where atom-representaion of face will be stored
     size_t *coatom_rep         # a place where coatom-representaion of face will be stored
     int current_dimension      # dimension of current face, dual dimension if ``dual``

src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx

@@ -414,7 +414,7 @@ cdef class FaceIterator_base(SageObject):
             self.structure.visited_all[self.structure.dimension -1].n_faces = 0
         else:
             self.structure.visited_all[self.structure.dimension -1].n_faces = 1
-        self.structure.face_status = 0
+        self.structure.face_status = FaceStatus.NOT_INITIALIZED
         self.structure.new_faces[self.structure.dimension - 1].n_faces = self.coatoms.n_faces()
         self.structure.current_dimension = self.structure.dimension - 1
         self.structure.highest_dimension = self.structure.dimension - 1
@@ -460,7 +460,7 @@ cdef class FaceIterator_base(SageObject):
             sage: next(it).ambient_V_indices() == it.current().ambient_V_indices()
             True
         """
-        if unlikely(self.structure.face_status == 0):
+        if unlikely(self.structure.face_status == FaceStatus.NOT_INITIALIZED):
             raise ValueError("iterator not set to a face yet")
         return CombinatorialFace(self)
 
@@ -888,7 +888,7 @@ cdef class FaceIterator_base(SageObject):
             sage: it._meet_of_coatoms(1, 2)
             A -1-dimensional face of a Polyhedron in QQ^2
         """
-        if unlikely(self.structure.face_status != 0):
+        if unlikely(self.structure.face_status != FaceStatus.NOT_INITIALIZED):
             raise ValueError("please reset the face iterator")
         if unlikely(self.structure.output_dimension != -2):
             raise ValueError("face iterator must not have the output dimension specified")
@@ -994,7 +994,7 @@ cdef class FaceIterator_base(SageObject):
             ...
             IndexError: atoms out of range
         """
-        if unlikely(self.structure.face_status != 0):
+        if unlikely(self.structure.face_status != FaceStatus.NOT_INITIALIZED):
             raise ValueError("please reset the face iterator")
         if unlikely(self.structure.output_dimension != -2):
             raise ValueError("face iterator must not have the output dimension specified")
@@ -1049,14 +1049,14 @@ cdef class FaceIterator_base(SageObject):
         See :meth:`FaceIterator_base.ignore_subfaces` and
         :meth:`FaceIterator_base.ignore_supfaces`.
         """
-        if unlikely(self.structure.face_status == 0):
+        if unlikely(self.structure.face_status == FaceStatus.NOT_INITIALIZED):
             raise ValueError("iterator not set to a face yet")
-        if unlikely(self.structure.face_status == 3):
+        if unlikely(self.structure.face_status == FaceStatus.ONLY_VISIT_SUBSETS):
             # The iterator is consumed, if it was just set to visit only subsets
             # next thing to ignore subsets.
             self.structure.current_dimension = self.structure.dimension
             return 0
-        if unlikely(self.structure.face_status == 2):
+        if unlikely(self.structure.face_status == FaceStatus.IGNORE_SUBSETS):
             # Nothing to do.
             return 0
         # The current face is added to ``visited_all``.
@@ -1065,7 +1065,7 @@ cdef class FaceIterator_base(SageObject):
         # as there are no new faces.
 
         add_face_shallow(self.structure.visited_all[self.structure.current_dimension], self.structure.face)
-        self.structure.face_status = 2
+        self.structure.face_status = FaceStatus.IGNORE_SUBSETS
 
     def only_subfaces(self):
         r"""
@@ -1177,9 +1177,9 @@ cdef class FaceIterator_base(SageObject):
         See :meth:`FaceIterator_base.only_subfaces` and
         :meth:`FaceIterator_base.only_supfaces`.
         """
-        if unlikely(self.structure.face_status == 0):
+        if unlikely(self.structure.face_status == FaceStatus.NOT_INITIALIZED):
             raise ValueError("iterator not set to a face yet")
-        if unlikely(self.structure.face_status == 2):
+        if unlikely(self.structure.face_status == FaceStatus.IGNORE_SUBSETS):
             raise ValueError("cannot only visit subsets after ignoring a face")
 
         cdef face_list_t* faces = &self.structure.new_faces[self.structure.current_dimension]
@@ -1191,7 +1191,7 @@ cdef class FaceIterator_base(SageObject):
 
         swap_faces(faces[0].faces[yet_to_visit], faces[0].faces[faces[0].n_faces - 1])
 
-        self.structure.face_status = 3
+        self.structure.face_status = FaceStatus.ONLY_VISIT_SUBSETS
         self.structure.yet_to_visit = 0
         # This will work:
         # ``next_dimension`` will first call ``next_face_loop`` and then check
@@ -1281,13 +1281,13 @@ cdef class FaceIterator_base(SageObject):
         if n_atoms == self.coatoms.n_atoms():
             # The face is the universe.
             self.structure.face[0] = face[0]
-            self.structure.face_status = 1
+            self.structure.face_status = FaceStatus.INITIALIZED
             self.structure.current_dimension = self.structure.dimension
             return 0
         elif n_atoms == 0:
             # The face is the empty face.
             self.structure.face[0] = face[0]
-            self.structure.face_status = 1
+            self.structure.face_status = FaceStatus.INITIALIZED
             self.structure.current_dimension = -1
             return 0
 
@@ -1928,7 +1928,7 @@ cdef inline int next_dimension(iter_t structure, size_t parallelization_depth=0)
     e.g. if it is ``1`` it will stop after having yield all faces of a facet
     """
     cdef int max_dim = structure.highest_dimension - parallelization_depth
-    structure.face_status = 0
+    structure.face_status = FaceStatus.NOT_INITIALIZED
     while (not next_face_loop(structure)) and (structure.current_dimension <= max_dim):
         sig_check()
     structure._index += 1
@@ -1959,7 +1959,7 @@ cdef inline int next_face_loop(iter_t structure) nogil except -1:
         # Set ``face`` to the next face.
         structure.yet_to_visit -= 1
         structure.face[0] = faces[0].faces[structure.yet_to_visit][0]
-        structure.face_status = 1
+        structure.face_status = FaceStatus.INITIALIZED
         return 1
 
     if structure.current_dimension <= structure.lowest_dimension: