diff --git a/docs/source/data-structures/order/index.rst b/docs/source/data-structures/order/index.rst index 6f371ce9..35ff1e80 100644 --- a/docs/source/data-structures/order/index.rst +++ b/docs/source/data-structures/order/index.rst @@ -15,7 +15,16 @@ or strings with respect to certain reduction orderings. .. seealso:: - :any:`Order`. + - :any:`Order` + - :any:`Alphabet` + +.. important:: + + The following functions are deprecated in v1.5.0 and will be removed v2.0.0: + + * ``lexicographical_compare``, please use :any:`lex_cmp` instead. + * ``recursive_path_compare`` please use :any:`rev_rpo_cmp` instead. + * ``shortlex_compare`` please use :any:`lenlex_cmp` instead. Contents -------- @@ -25,11 +34,8 @@ Contents lenlex_cmp lex_cmp - lexicographical_compare - recursive_path_compare rev_rpo_cmp rpo_cmp - shortlex_compare Full API -------- @@ -38,12 +44,6 @@ Full API .. autofunction:: lex_cmp -.. autofunction:: lexicographical_compare - -.. autofunction:: recursive_path_compare - .. autofunction:: rev_rpo_cmp .. autofunction:: rpo_cmp - -.. autofunction:: shortlex_compare diff --git a/src/order.cpp b/src/order.cpp index 8e05b195..1953dd65 100644 --- a/src/order.cpp +++ b/src/order.cpp @@ -45,36 +45,11 @@ namespace libsemigroups { } } - template - void bind_compare(py::module& m, - char const* name, - Compare compare, - AlphabetCompare alphabet_compare, - char const* doc) { - m.def( - name, - [compare](Word const& x, Word const& y) { return compare(x, y); }, - py::arg("x"), - py::arg("y"), - doc); - m.def( - name, - [alphabet_compare]( - Alphabet const& alphabet, Word const& x, Word const& y) { - return alphabet_compare(alphabet, x, y); - }, - py::arg("alphabet"), - py::arg("x"), - py::arg("y"), - doc); - } - template void bind_deprecated_compare(py::module& m, char const* old_name, char const* new_name, - Compare compare, - char const* doc) { + Compare compare) { m.def( old_name, [old_name, new_name, compare](Word const& x, Word const& y) { @@ -82,52 +57,82 @@ namespace libsemigroups { return compare(x, y); }, py::arg("x"), - py::arg("y"), - doc); + py::arg("y")); } template void bind_order_comparisons(py::module& m) { - bind_compare( - m, + m.def( "lex_cmp", [](Word const& x, Word const& y) { return lex_cmp(x, y); }, + py::arg("x"), + py::arg("y"), + R"pbdoc( +:sig=(x: str | list[int], y: str | list[int]) -> bool: +:only-document-once: +Compare two words lexicographically. + +:param x: the first word. +:type x: str | list[int] +:param y: the second word. +:type y: str | list[int] +:returns: Whether *x* is less than *y*. +:rtype: bool + +.. doctest:: python + + >>> from libsemigroups_pybind11 import lex_cmp + >>> lex_cmp("ab", "ba") + True + >>> lex_cmp([0, 1], [1, 0]) + True +)pbdoc"); + + m.def( + "lex_cmp", [](Alphabet const& alphabet, Word const& x, Word const& y) { return lex_cmp(alphabet, x, y); }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words lexicographically. +Compare two words lexicographically using an alphabet. -The three-argument overload ``lex_cmp(alphabet, x, y)`` compares letters by -their positions in *alphabet*. It raises :any:`LibsemigroupsError` if either -word contains a letter that does not belong to *alphabet*. +Letters are compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, lex_cmp + >>> alphabet = Alphabet("ba") + >>> lex_cmp(alphabet, "b", "a") + True )pbdoc"); - bind_compare( - m, + m.def( "lenlex_cmp", [](Word const& x, Word const& y) { return lenlex_cmp(x, y); }, - [](Alphabet const& alphabet, Word const& x, Word const& y) { - return lenlex_cmp(alphabet, x, y); - }, + py::arg("x"), + py::arg("y"), R"pbdoc( :sig=(x: str | list[int], y: str | list[int]) -> bool: :only-document-once: Compare two words using len-lex ordering. -Words are first ordered by length and then lexicographically. The -three-argument overload ``lenlex_cmp(alphabet, x, y)`` compares letters by -their positions in *alphabet*. It raises :any:`LibsemigroupsError` if either -word contains a letter that does not belong to *alphabet*. +Words are first ordered by length and then lexicographically. :param x: the first word. :type x: str | list[int] @@ -135,53 +140,60 @@ word contains a letter that does not belong to *alphabet*. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool + +.. doctest:: python + + >>> from libsemigroups_pybind11 import lenlex_cmp + >>> lenlex_cmp("bb", "aaa") + True + >>> lenlex_cmp([1, 1], [0, 0, 0]) + True )pbdoc"); - bind_compare( - m, - "rpo_cmp", - [](Word const& x, Word const& y) { return rpo_cmp(x, y); }, + m.def( + "lenlex_cmp", [](Alphabet const& alphabet, Word const& x, Word const& y) { - return rpo_cmp(alphabet, x, y); + return lenlex_cmp(alphabet, x, y); }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using recursive-path ordering. +Compare two words using len-lex ordering and an alphabet. -The three-argument overload ``rpo_cmp(alphabet, x, y)`` compares letters by -their positions in *alphabet*. It raises :any:`LibsemigroupsError` if either -word contains a letter that does not belong to *alphabet*. +Words are first ordered by length and then lexicographically, with letters +compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. -.. warning:: - This function has significantly worse performance than :any:`lenlex_cmp` - and :any:`lex_cmp`. +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, lenlex_cmp + >>> alphabet = Alphabet("ba") + >>> lenlex_cmp(alphabet, "b", "a") + True )pbdoc"); - bind_compare( - m, - "rev_rpo_cmp", - [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }, - [](Alphabet const& alphabet, Word const& x, Word const& y) { - return rev_rpo_cmp(alphabet, x, y); - }, + m.def( + "rpo_cmp", + [](Word const& x, Word const& y) { return rpo_cmp(x, y); }, + py::arg("x"), + py::arg("y"), R"pbdoc( :sig=(x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using reversed recursive-path ordering. - -This is recursive-path ordering applied after reading both words from right to -left. The three-argument overload ``rev_rpo_cmp(alphabet, x, y)`` compares -letters by their positions in *alphabet*. It raises -:any:`LibsemigroupsError` if either word contains a letter that does not belong -to *alphabet*. +Compare two words using recursive-path ordering. :param x: the first word. :type x: str | list[int] @@ -193,39 +205,66 @@ to *alphabet*. .. warning:: This function has significantly worse performance than :any:`lenlex_cmp` and :any:`lex_cmp`. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import rpo_cmp + >>> rpo_cmp("a", "b") + True + >>> rpo_cmp([0], [1]) + True )pbdoc"); - bind_deprecated_compare( - m, - "lexicographical_compare", - "lex_cmp", - [](Word const& x, Word const& y) { return lex_cmp(x, y); }, + m.def( + "rpo_cmp", + [](Alphabet const& alphabet, Word const& x, Word const& y) { + return rpo_cmp(alphabet, x, y); + }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words lexicographically. +Compare two words using recursive-path ordering and an alphabet. + +Letters are compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. + +.. warning:: + This function has significantly worse performance than :any:`lenlex_cmp` + and :any:`lex_cmp`. + +.. doctest:: python -.. deprecated:: 1.5 - This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use - :any:`lex_cmp`. + >>> from libsemigroups_pybind11 import Alphabet, rpo_cmp + >>> alphabet = Alphabet("ba") + >>> rpo_cmp(alphabet, "b", "a") + True )pbdoc"); - bind_deprecated_compare( - m, - "shortlex_compare", - "lenlex_cmp", - [](Word const& x, Word const& y) { return lenlex_cmp(x, y); }, + m.def( + "rev_rpo_cmp", + [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }, + py::arg("x"), + py::arg("y"), R"pbdoc( :sig=(x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using len-lex ordering. +Compare two words using reversed recursive-path ordering. + +This is recursive-path ordering applied after reading both words from right to +left. :param x: the first word. :type x: str | list[int] @@ -234,32 +273,75 @@ Compare two words using len-lex ordering. :returns: Whether *x* is less than *y*. :rtype: bool -.. deprecated:: 1.5 - This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use - :any:`lenlex_cmp`. +.. warning:: + This function has significantly worse performance than :any:`lenlex_cmp` + and :any:`lex_cmp`. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import rev_rpo_cmp + >>> rev_rpo_cmp("a", "b") + True + >>> rev_rpo_cmp([0], [1]) + True )pbdoc"); - bind_deprecated_compare( - m, - "recursive_path_compare", + m.def( "rev_rpo_cmp", - [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }, + [](Alphabet const& alphabet, Word const& x, Word const& y) { + return rev_rpo_cmp(alphabet, x, y); + }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using reversed recursive-path ordering. +Compare two words using reversed recursive-path ordering and an alphabet. + +This is recursive-path ordering applied after reading both words from right to +left, with letters compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. + +.. warning:: + This function has significantly worse performance than :any:`lenlex_cmp` + and :any:`lex_cmp`. -.. deprecated:: 1.5 - This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use - :any:`rev_rpo_cmp`. +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, rev_rpo_cmp + >>> alphabet = Alphabet("ba") + >>> rev_rpo_cmp(alphabet, "b", "a") + True )pbdoc"); + + bind_deprecated_compare( + m, + "lexicographical_compare", + "lex_cmp", + [](Word const& x, Word const& y) { return lex_cmp(x, y); }); + + bind_deprecated_compare( + m, + "shortlex_compare", + "lenlex_cmp", + [](Word const& x, Word const& y) { return lenlex_cmp(x, y); }); + + bind_deprecated_compare( + m, + "recursive_path_compare", + "rev_rpo_cmp", + [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }); } } // namespace @@ -322,8 +404,16 @@ respectively, in new code. The recursive-path ordering, as described in :cite:`Jantzen2012aa` (Definition 1.2.14, page 24). - + This is deprecated; use :any:`Order.rpo` instead. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Order + >>> Order.lenlex + + >>> Order.shortlex == Order.lenlex + True )pbdoc") .value("none", Order::none) .value("lenlex", Order::lenlex)