presentation: add index_rule

Author: james-d-mitchell

docs/source/data-structures/presentations/present-helpers.rst

@@ -47,6 +47,7 @@ Contents
     first_unused_letter
     greedy_reduce_length
     greedy_reduce_length_and_number_of_gens
+    index_rule
     is_strongly_compressible
     length
     longest_rule

src/libsemigroups_pybind11/presentation/__init__.py

@@ -54,6 +54,7 @@
     presentation_to_gap_string as _to_gap_string,
     presentation_balance as _balance,
     presentation_add_cyclic_conjugates as _add_cyclic_conjugates,
+    presentation_index_rule as _index_rule,
 )
 
 from libsemigroups_pybind11.detail.cxx_wrapper import (
@@ -267,3 +268,4 @@ def __init__(self: _Self, *args, **kwargs) -> None:
 to_gap_string = _wrap_cxx_free_fn(_to_gap_string)
 balance = _wrap_cxx_free_fn(_balance)
 add_cyclic_conjugates = _wrap_cxx_free_fn(_add_cyclic_conjugates)
+index_rule = _wrap_cxx_free_fn(_index_rule)

src/present.cpp

@@ -1397,6 +1397,40 @@ empty word to the presentation *p*, for every cyclic permutation ``w`` of
   if *relator* contains any letters not belonging to ``p.alphabet()``.
 
 :raises LibsemigroupsError:  if *p* does not contain the empty word.)pbdoc");
+
+      // We do not bind presentation::find_rule because it returns an iterator
+      //
+      m.def(
+          "presentation_index_rule",
+          [](Presentation<Word>& p, Word const& lhs, Word const& rhs) {
+            return from_int(presentation::index_rule(p, lhs, rhs));
+          },
+          py::arg("p"),
+          py::arg("lhs"),
+          py::arg("rhs"),
+          R"pbdoc(
+:sig=(p: Presentation, lhs: Word, rhs: Word) -> int | Undefined:
+:only-document-once:
+
+Returns the index of a rule or :any:`UNDEFINED`.
+
+This function returns the minimum index ``i`` of *lhs* such that ``p.rules[i +
+1]`` equals *rhs* ; or :any:`UNDEFINED` if there is not such rule
+
+:param p: the presentation.
+:type p: Presentation
+
+:param lhs: the left-hand side of the rule.
+:type lhs: :ref:`Word<pseudo_word_type_helper>`
+
+:param rhs: the right-hand side of the rule.
+:type rhs: :ref:`Word<pseudo_word_type_helper>`
+
+:returns: The index of the rule or :any:`UNDEFINED`.
+:rtype: int | Undefined
+
+:raises LibsemigroupsError:  if ``p.throw_if_bad_alphabet_or_rules()`` throws.
+)pbdoc");
     }  // bind_present
 
     template <typename Word>

tests/test_present.py

@@ -2192,3 +2192,12 @@ def test_presentation_add_cyclic_conjugates():
         presentation.add_cyclic_conjugates(p, "abcaabbcc")
     with pytest.raises(LibsemigroupsError):
         presentation.add_cyclic_conjugates(p, "dadadad")
+
+
+def test_presentation_index_rule():
+    p = Presentation("abc")
+    p.contains_empty_word(True)
+    p.rules = ["aaaa", ""]
+
+    assert presentation.index_rule(p, "aaaa", "") == 0
+    assert presentation.index_rule(p, "a", "") == UNDEFINED