Fix argument checking in FreeSemigroup, prevent creation of inconsistent objects

[wilfwilson]

See #1385.

It was previously possible to use FreeSemigroup to create a seemingly free semigroup with zero generators (rank zero), but this object believed itself to be infinite, and to contain elements (such a semigroup would be empty). Note that free semigroups of rank zero are not documented as being supported.

Some other ways that one might want to create free semigroups of rank zero led to unhelpful error messages, and in general, the argument checking of FreeSemigroup was not very thorough and gave sometimes unhelpful error messages.

In this commit, I overhaul the way that FreeSemigroup checks its arguments, in particular always disallowing a free semigroup of rank zero, and overall making the checking more robust, and making the error messages more descriptive.

This addresses the bugs reported in issue #1385, although it does not address the feature request in that issue to support free semigroups of rank zero.

I also took the opportunity to fix a typo in the documentation for FreeSemigroup, and to make a clarification. Further improvements could be made to this documentation, but I leave that to the future.

Description

Text for release notes

Fix bugs caused when calling FreeSemigroup with incorrect arguments.

(End of text for release notes)

[fingolfin]

Just to verify: issue #1385 also mentions FreeMagma, but I think this PR does nothing about that, right?

[fingolfin]

Looks good to me, thanks!

[wilfwilson]

Correct, this PR doesn't do anything about FreeMagma.

In my opinion, #1385 is about two things: a wrong-result bug report (FreeSemigroup([]) giving a semigroup of size infinity) and a feature request (FreeSemigroup and FreeMagma should support the creation of free semigroups and magmas with zero generators).

The primary purpose of this PR was to deal with the wrong-result bug in preparation for GAP 4.12.0. Given the way that the issue was written, I assumed that the wrong-result bug only applied FreeSemigroup. But it applies to FreeMagma too (and possibly other such functions).

I'll have a think about whether I want to do to address this too, and if so how. I don't want this to snowball 🙂!

The code for FreeMagma (I assume) should probably be an almost-duplicate of the code for FreeSemigroup (and for FreeMagmaWithOne? and FreeMonoid?). But I think it would be silly to duplicate so much technical code. So perhaps I'll refactor them to combine them.

I will probably create a new issue, as a feature request for supporting these things on zero generators – unless it turns out that it makes much more sense to just combine all those changes in this one PR.

[fingolfin]

This PR has a "do not merge" label. So, what is left to be done?

[wilfwilson]

#4372 (comment):

I'll have a think about whether I want to do to address this too, and if so how.

I wanted to decide whether this PR should also deal with FreeMagma (and FreeMonoid and FreeMagmaWithOne). But I think I've just decided now that I'll deal with those in a separate PR.