Documentation discusses queues, but doesn't document how to create one

[james-d-mitchell]

There's documentation in the manual for queues and deques, which suggests that it's possible to create a Queue, but there's no documentation about how to do this:

https://gap-packages.github.io/datastructures/doc/chap4.html#X7E4B7210874702B2

Looking at the source code, it's not clear to me whether or not Queues are actually implemented in datastructures, there are deque's for sure. This is either a missing documentation issue (i.e. queues exist in datastructures but how to construct one isn't documented); or a bug in the documentation (i.e. queues don't exist in datastructures and so maybe should be in the documentation?).

I'd be happy to amend the doc in a PR if someone could let me know what the correct thing to do is.

[james-d-mitchell]

Maybe this should be a separate issue, but looking at the tests etc for Deques, it'd be good if Deques could be used like Stacks can. In particular, there's PlistDeque, PlistDequePeekBack, etc, but there's no PlistStack just Stack. Yesterday I tried to use Queue like Stack and failed (because it doesn't exist), and then was confused by the disparity between the usage of Stack and Deque, and the seeming non-existence of Queue. Maybe there's a good reason for this, but maybe also this is a little over-engineered?

Would a PR which cleans up Deque to offer a comparable interface to Stack be something that'd be welcome?

[fingolfin]

When we created the package, Markus was very excited about adding a ton of things, and he added a ton of place holders for stuff (and of course also implementation). In this case, I don't think we have had an implementation of a pure queue in the repository. It shouldn't be hard to add a "trivial" pure GAP implementation, though, of course, if someone was interested.

(This may also be partially because the main GAP repository has NewQueue and a few other things when used in HPC-GAP... But without any documentation... I think that implementation should be renamed to make it crystal clear it is internal only.)

And I agree that some things there are over-engineered. E.g. Enqueue and Dequeue should just go.

[fingolfin]

Oh and I think the intention was that eventually the constructors like NewDeque are used.

Finally, I don't think PlistDequePushBack is meant to be used directly; it is installed as a method for PushBack, which should be used instead... I am guessing we have it as a function of its own for "speed freaks" who absolutely want to avoid method dispatch overhead? I am not quite sure, though. It could also just be a case of something that was in the middle of a redesign and then never was finished up (I never really dealt with the queue/deque/stack code, I was working on hashtables and binary heaps)