bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Drew Adams]

Please explicitly say that `remq' returns a *copy* of LIST, just as we
do in the doc string of `remove'.  It does *not* "Return LIST with all
occurrences of ELT removed."  

The final sentence of the doc string tries to clarify things, but
combined with the first sentence the result is still confusing.



In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Christoph]

[-- Attachment #1: Type: text/plain, Size: 867 bytes --]

Thanks for the report. Fixed in trunk r117732.


On Tue, Aug 12, 2014 at 8:59 AM, Drew Adams <drew.adams@oracle.com> wrote:

>
> Please explicitly say that `remq' returns a *copy* of LIST, just as we
> do in the doc string of `remove'.  It does *not* "Return LIST with all
> occurrences of ELT removed."
>
> The final sentence of the doc string tries to clarify things, but
> combined with the first sentence the result is still confusing.
>
>
>
> In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
>  of 2014-06-28 on ODIEONE
> Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
> Windowing system distributor `Microsoft Corp.', version 6.1.7601
> Configured using:
>  `configure --prefix=/c/Devel/emacs/snapshot/trunk
>  --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
>  LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
>  -Ic:/Devel/emacs/include''
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 1288 bytes --]

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[tsugutomo.enami]

Hi,

> Thanks for the report. Fixed in trunk r117732.
> 
> On Tue, Aug 12, 2014 at 8:59 AM, Drew Adams <drew.adams@oracle.com> wrote:
> 
> >
> > Please explicitly say that `remq' returns a *copy* of LIST, just as we
> > do in the doc string of `remove'.  It does *not* "Return LIST with all
> > occurrences of ELT removed."

IMHO, describing remq to return a copy of list is also confusing.  Since
it does not return a copy on some cases.

enami.

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Drew Adams]

> > > Please explicitly say that `remq' returns a *copy* of LIST, just as we
> > > do in the doc string of `remove'.  It does *not* "Return LIST with all
> > > occurrences of ELT removed."
> 
> IMHO, describing remq to return a copy of list is also confusing.  Since
> it does not return a copy on some cases.

Good point. Perhaps it should say that it returns either a copy or a
tail of the list.  It could say something like this, for example:

 If the only elements in LIST that are `eq' to ELT occur before any
 other elements then a copy is not made: the tail after the last such
 occurrence is returned.

Whatever language we choose, it should be precise wrt what the behavior
is.

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Stefan Monnier]

>  If the only elements in LIST that are `eq' to ELT occur before any
>  other elements then a copy is not made: the tail after the last such
>  occurrence is returned.
> Whatever language we choose, it should be precise wrt what the behavior
> is.

I don't see a need for precision.  It should just say that the returned list
may share some elements with the original argument, but that no element
was modified by side-effect.


        Stefan

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Drew Adams]

> It should just say that the returned list may share some elements
> with the original argument, but that no element was modified by
> side-effect.

Why would the question of whether an *element* was modified even come
up?  That seems like a red herring, bound only to confuse people.
The question that arises for users is about sharing/modification of
the list structure, not elements.  (Yes, of course an element can
itself be a list.)

There is nothing wrong with letting users know the actual behavior.
It would be helpful to provide the kind of information that Emacs
provides (and all Lisps provide) for `member': "The value is actually
the tail of LIST whose car is ELT."

But the main point - the point of the bug report, is that it is not
correct to say, as we say now, that `remq' "Returns LIST with all
occurrences of ELT removed."  It does that only when all of the ELT
occurrences occur before any non-ELT occurrences.

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Stefan Monnier]

> There is nothing wrong with letting users know the actual behavior.

Of course there is: there is another possible behavior, which would
generally be superior but which we didn't bother to implement (yet).


        Stefan

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Drew Adams]

> > There is nothing wrong with letting users know the actual behavior.
> 
> Of course there is: there is another possible behavior, which would
> generally be superior but which we didn't bother to implement (yet).

That's a pretty facile "of course".  Of course you can document now
the behavior it has now, and if and when you ever change the behavior
you can update the doc accordingly.  It's not like you just invented
`remq' - it's nearly as old as Lisp (at least as old as ZetaLisp).

And most (all other?) Lisps have given it the same behavior as `remove',
the only difference being to use `eq' instead of `equal'.  IOW, they
systematically copy the sequence.  All the more reason to let users
know that Emacs Lisp is exceptional in this regard.

It is this part of the Emacs definition that differs from the usual
definition, and makes Emacs `remq' unparallel with Emacs `remove':

  (while (and (eq elt (car list)) (setq list (cdr list))))

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[tsugutomo.enami]

Hi,

> And most (all other?) Lisps have given it the same behavior as `remove',
> the only difference being to use `eq' instead of `equal'.  IOW, they
> systematically copy the sequence.

How about to avoid the use of word `copy' to describe both `remq' and
`remove'?

The point of remq/remove is non-destructive operation.  Whether it
returns a copy or not is not important.  This matches CL's `remove'
definition.  Actually, even the current `remove' implementation does not
return a copy when SEQ is not a list and there is nothing to remove.

If document explicitly says it returns a copy, reader might think
destructive operation can be performed on the result of both functions
while expecting original sequence unmodified.

enami.

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[Drew Adams]

> > And most (all other?) Lisps have given it the same behavior as
> > `remove', the only difference being to use `eq' instead of `equal'.
> > IOW, they systematically copy the sequence.
> 
> How about to avoid the use of word `copy' to describe both `remq'
> and `remove'?

Because that is precisely what is important.  Why "avoid" what it
is most important to communicate to users?

> The point of remq/remove is non-destructive operation.  Whether it
> returns a copy or not is not important.  This matches CL's `remove'
> definition.

No, it does not.  From CLTL, section 14.3, "Modifying Sequences":

  The result is a sequence of the same kind as the argument SEQUENCE
  that has the same elements except that those in the subsequence
  delimited by :start and :end and satisfying the test (see above)
  have been removed.  This is a non-destructive operation; the result
  is a copy of the input SEQUENCE, save that some elements are not
  ^^^^^^^^^
  copied.  Elements not removed occur in the same order in the result
  ^^^^^^
  that they did in the argument.

That text was in the original edition of CTLT (1984), and it has not
changed one bit in subsequent revisions.

> Actually, even the current `remove' implementation does
> not return a copy when SEQ is not a list and there is nothing to
> remove.

I did not check the C code, but all descriptions of Elisp `delete'
for a non-list say that it *always* returns a new object.  Perhaps
all of those descriptions are incorrect (?), in which case we have
a bigger doc problem.

> If document explicitly says it returns a copy, reader might think
> destructive operation can be performed on the result of both
> functions while expecting original sequence unmodified.

Which is the case for Common Lisp.  And which should be the case
for Emacs Lisp for the cases that need to be documented as such
(i.e. as copying).

bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

[tsugutomo.enami]

Hi,

I guess the specification of Emacs's remove/remq should be clarified
first.

If current implementaion is correctly reflecting the specification, then
I hope it is documented that those function might not return a copy on
some case (in other words, document which can be read as if they always
return a copy is confusing).

If current implementaion is not correct, then they should be fixed (and
documentation is updated to reflect the specification, if necessary).

> > The point of remq/remove is non-destructive operation.  Whether it
> > returns a copy or not is not important.  This matches CL's `remove'
> > definition.
> 
> No, it does not.  From CLTL, section 14.3, "Modifying Sequences":
> 
>   The result is a sequence of the same kind as the argument SEQUENCE
>   that has the same elements except that those in the subsequence
>   delimited by :start and :end and satisfying the test (see above)
>   have been removed.  This is a non-destructive operation; the result
>   is a copy of the input SEQUENCE, save that some elements are not
>   ^^^^^^^^^
>   copied.  Elements not removed occur in the same order in the result
>   ^^^^^^
>   that they did in the argument.
> 
> That text was in the original edition of CTLT (1984), and it has not
> changed one bit in subsequent revisions.

Probably, I failed to pick up my word.  What I meant was that those
function might not return a copy and they doesn't modify its argument is
more important aspect.  Of course it is importatnt to copy cells when
necessary.

The `remove' might not return a copy is described in the last sentense
of the section (quoted from
https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node144.html):

  The result of remove may share with the argument sequence; a list
  result may share a tail with an input list, and the result may be eq
  to the input sequence if no elements need to be removed.

enami.