Update transf

[james-d-mitchell]

No description provided.

[james-d-mitchell]

Work in progress, just opening a PR for visibility

[jswent]

@james-d-mitchell just added the changes I had committed locally to this PR so it doesn't mess you up. Note that the ! convention in Julia (e.g. increase_degree_by!) indicates a method which mutates its input object in place.

[jswent]

@james-d-mitchell I also moved the docs to a separate pr

[james-d-mitchell]

This error message shouldn't be necessary, there's a check in the c+ code.

[jswent]

@james-d-mitchell I can't seem to find an exception being thrown in the c++ code. I tested the c++ with:

auto t = make<Transf<0, uint8_t>>({0});
std::cout << "Degree before: " << t.degree() << "\n";

t.increase_degree_by(300);  // No exception thrown
std::cout << "Degree after:  " << t.degree() << "\n\n";

std::cout << "t[254] = " << (int)t[254] << " (expected 254)\n";
std::cout << "t[255] = " << (int)t[255] << " (expected 255)\n";
std::cout << "t[256] = " << (int)t[256] << " (expected 256)\n";
std::cout << "t[257] = " << (int)t[257] << " (expected 257)\n";

I get:

Degree before: 1
Degree after:  301

t[254] = 254 (expected 254)
t[255] = 255 (expected 255)
t[256] = 0 (expected 256)
t[257] = 1 (expected 257)

Looking at the Python bindings, they handle this in the Python wrapper layer: https://github.com/libsemigroups/libsemigroups_pybind11/blob/ed041e62327c2a94abe4deba2ccb2773ee0c41df/src/libsemigroups_pybind11/transf.py#L135-L144

which also promotes the type: https://github.com/libsemigroups/libsemigroups_pybind11/blob/ed041e62327c2a94abe4deba2ccb2773ee0c41df/src/libsemigroups_pybind11/transf.py#L145-L149

[jswent]

Is this the desired behavior (degree just wraps around) and type promotion is only done due to Python simplicity, or do we want that here as well?