On Thu, Nov 16, 2023 at 4:42 PM Eli Zaretskii <
eliz@gnu.org> wrote:
> ?? There's a whole section in the ELisp manual called "Sequence
> Functions", which documents the seq-* functions.
Yes, but from a custom sequence implementors perspective,
custom sequence".
So while the Elisp manual addresses custom sequences
(very briefly -- it just tells the user to look up generic
functions) it spends most time describing the generic
functions one by one, and while that's important, it's
just not enough.
It doesn't talk about the guarantees that the framework
offers with respect to when they are called, or if they
are called at all. For example, while I didn't read the
whole thing, I don't think it is stated that custom sequences
based on Lisp lists need many more gf implementations
than others, else they simply won't work (because of
list-specific shortcutting optimizations only found
when reading the seq.el code). Nor is it stated that, for
any representation, :around methods are probably a bad
idea. Nor is it stated that if you just implement the bare
minimum (which is described in seq.el's header) you will
likely get very poor performance.
Such a manual is where one would find sentences like
"to make a working custom sequence that is accepted by
any seq-* call, the user must add implementations to
the following N generics. To get good performance
you must also add implementations to these other M
generics". (Dmitry's proposed seq-contains-pred would
be in this set).
João