Add nonspanning_circuits_iterator and improve docstrings

src/sage/matroids/circuits_matroid.pyx

@@ -2,15 +2,16 @@ r"""
 Circuits matroids
 
 Matroids are characterized by a list of circuits, which are minimal dependent
-sets. The CircuitsMatroid class implements matroids using this information as
-data.
+sets. The ``CircuitsMatroid`` class implements matroids using this information
+as data.
 
 A ``CircuitsMatroid`` can be created from another matroid or from a list of
 circuits. For a full description of allowed inputs, see
 :class:`below <sage.matroids.circuits_matroid.CircuitsMatroid>`. It is
 recommended to use the :func:`Matroid() <sage.matroids.constructor.Matroid>`
-function for a more flexible construction of a ``CircuitsMatroid``. For direct
-access to the ``CircuitsMatroid`` constructor, run::
+function for a more flexible way of constructing a ``CircuitMatroid`` and other
+classes of matroids. For direct access to the ``CircuitsMatroid`` constructor,
+run::
 
     sage: from sage.matroids.circuits_matroid import CircuitsMatroid
 
@@ -425,6 +426,10 @@ cdef class CircuitsMatroid(Matroid):
         """
         Return the circuits of the matroid.
 
+        INPUT:
+
+        - ``k`` -- an integer (optional); the length of the circuits
+
         OUTPUT: a SetSystem
 
         EXAMPLES::
@@ -449,6 +454,10 @@ cdef class CircuitsMatroid(Matroid):
         """
         Return an iterator over the circuits of the matroid.
 
+        INPUT:
+
+        - ``k`` -- an integer (optional); the length of the circuits
+
         EXAMPLES::
 
             sage: from sage.matroids.circuits_matroid import CircuitsMatroid
@@ -485,6 +494,24 @@ cdef class CircuitsMatroid(Matroid):
                     NSC.append(C)
         return NSC
 
+    def nonspanning_circuits_iterator(self):
+        """
+        Return the list of nonspanning circuits of the matroid.
+
+        OUTPUT: a SetSystem
+
+        EXAMPLES::
+
+            sage: from sage.matroids.circuits_matroid import CircuitsMatroid
+            sage: M = CircuitsMatroid(matroids.Uniform(2, 4))
+            sage: list(M.nonspanning_circuits_iterator())
+            []
+        """
+        for i in self._k_C:
+            if i <= self.rank():
+                for C in self._k_C[i]:
+                    yield C
+
     cpdef no_broken_circuits_sets(self, ordering=None) noexcept:
         r"""
         Return the no broken circuits (NBC) sets of ``self``.