bug#64960: Documentation for copy-sequence

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Have been reading the documentation for "copy-sequence".  The description,
specifically

"The elements of a list, vector or record are not copied; they are
shared with the original."

is not very clear about what it does and what one gets.

--------------------

copy-sequence is a built-in function in ‘C source code’.

(copy-sequence ARG)

Type: (function (sequence) sequence)

Return a copy of a list, vector, string, char-table or record.
The elements of a list, vector or record are not copied; they are
shared with the original.

If the original sequence is empty, this function may return
the same empty object instead of its copy.

This function does not change global state, including the match data.

bug#64960: Documentation for copy-sequence

[Eli Zaretskii]

> Date: Sun, 30 Jul 2023 16:42:28 +0000
> From:  uzibalqa via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Have been reading the documentation for "copy-sequence".  The description,
> specifically
> 
> "The elements of a list, vector or record are not copied; they are
> shared with the original."
> 
> is not very clear about what it does and what one gets.

As the doc string says: the elements are not copied.  You get a new
sequence whose elements are shared with the original one.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Sent with Proton Mail secure email.

------- Original Message -------
On Monday, July 31st, 2023 at 6:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:


> > Date: Sun, 30 Jul 2023 16:42:28 +0000
> > From: uzibalqa via "Bug reports for GNU Emacs,
> > the Swiss army knife of text editors" bug-gnu-emacs@gnu.org
> > 
> > Have been reading the documentation for "copy-sequence". The description,
> > specifically
> > 
> > "The elements of a list, vector or record are not copied; they are
> > shared with the original."
> > 
> > is not very clear about what it does and what one gets.
> 
> 
> As the doc string says: the elements are not copied. You get a new
> sequence whose elements are shared with the original one.
> 

So it returns a copy but elements are not copied.  So what happens exactly ?
You get a reference to the original ?  When I modify the copy, the original 
remains intact.  It would help if the description in broadened, it is currently
too cryptic.

bug#64960: Documentation for copy-sequence

[Dmitry Gutov]

On 30/07/2023 22:20, uzibalqa via Bug reports for GNU Emacs, the Swiss 
army knife of text editors wrote:
> So it returns a copy but elements are not copied.  So what happens exactly ?
> You get a reference to the original ?  When I modify the copy, the original
> remains intact.

The list (if the sequence is a list) is new (from newly allocated cons 
cells), but the values inside (in cars of those conses) are shared with 
the original list.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Monday, July 31st, 2023 at 7:59 AM, Dmitry Gutov <dmitry@gutov.dev> wrote:


> On 30/07/2023 22:20, uzibalqa via Bug reports for GNU Emacs, the Swiss
> army knife of text editors wrote:
> 
> > So it returns a copy but elements are not copied. So what happens exactly ?
> > You get a reference to the original ? When I modify the copy, the original
> > remains intact.
> 
> 
> The list (if the sequence is a list) is new (from newly allocated cons
> cells), but the values inside (in cars of those conses) are shared with
> the original list.

It is not evident what the meaning of "shared" means ?  If I use a string,
I get an exact copy and when I change a single character the newlist is 
changed,  the original string remains the same.  So what is shared exactly ?

bug#64960: Documentation for copy-sequence

[Dmitry Gutov]

On 30/07/2023 23:09, uzibalqa wrote:
> It is not evident what the meaning of "shared" means ?  If I use a string,
> I get an exact copy and when I change a single character the newlist is
> changed,  the original string remains the same.  So what is shared exactly ?

A string doesn't share anything because characters are not reference 
values. They are simply copied.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Monday, July 31st, 2023 at 8:15 AM, Dmitry Gutov <dmitry@gutov.dev> wrote:


> On 30/07/2023 23:09, uzibalqa wrote:
> 
> > It is not evident what the meaning of "shared" means ? If I use a string,
> > I get an exact copy and when I change a single character the newlist is
> > changed, the original string remains the same. So what is shared exactly ?
> 
> 
> A string doesn't share anything because characters are not reference
> values. They are simply copied.

So why does the description also refer to a string.  With strings, things
do not work like the description.

(copy-sequence ARG)

bug#64960: Documentation for copy-sequence

[Drew Adams]

> > It is not evident what the meaning of "shared" means ?  If I use a
> > string, I get an exact copy and when I change a single character
> > the newlist is changed,  the original string remains the same.
> > So what is shared exactly ?
> 
> A string doesn't share anything because characters are not reference
> values. They are simply copied.

Yes and no.
Chars are not shared, but char properties are.

(setq foo (propertize "abcd" 'p1 t 'p2 42))
;; -> #("abcd" 0 4 (p2 42 p1 t))
(setq bar (copy-sequence foo))
;; -> #("abcd" 0 4 (p1 t p2 42))
(aset foo 1 ?W) ; -> ?W, aka 87
foo ; -> #("aWcd" 0 4 (p2 42 p1 t))
bar ; -> #("abcd" 0 4 (p1 t p2 42))

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Monday, July 31st, 2023 at 1:13 PM, Drew Adams <drew.adams@oracle.com> wrote:


> > > It is not evident what the meaning of "shared" means ? If I use a
> > > string, I get an exact copy and when I change a single character
> > > the newlist is changed, the original string remains the same.
> > > So what is shared exactly ?
> > 
> > A string doesn't share anything because characters are not reference
> > values. They are simply copied.
> 
> 
> Yes and no.
> Chars are not shared, but char properties are.
> 
> (setq foo (propertize "abcd" 'p1 t 'p2 42))
> ;; -> #("abcd" 0 4 (p2 42 p1 t))
> 
> (setq bar (copy-sequence foo))
> ;; -> #("abcd" 0 4 (p1 t p2 42))
> 
> (aset foo 1 ?W) ; -> ?W, aka 87
> 
> foo ; -> #("aWcd" 0 4 (p2 42 p1 t))
> 
> bar ; -> #("abcd" 0 4 (p1 t p2 42))

Ok, meaning that the actual string becomes different, yet changing
the a property, changes the property on both foo and bar ?

bug#64960: Documentation for copy-sequence

[Drew Adams]

> > > A string doesn't share anything because characters are not reference
> > > values. They are simply copied.
> >
> >
> > Yes and no.
> > Chars are not shared, but char properties are.
> >
> > (setq foo (propertize "abcd" 'p1 t 'p2 42))
> > ;; -> #("abcd" 0 4 (p2 42 p1 t))
> > (setq bar (copy-sequence foo))
> > ;; -> #("abcd" 0 4 (p1 t p2 42))
> > (aset foo 1 ?W) ; -> ?W, aka 87
> > foo ; -> #("aWcd" 0 4 (p2 42 p1 t))
> > bar ; -> #("abcd" 0 4 (p1 t p2 42))
> 
> Ok, meaning that the actual string becomes different, yet changing
> the a property, changes the property on both foo and bar ?

No.  I didn't change a property.  I swapped one
char for another.  The doc says that the arg's
"elements" are shared.  A string's "elements"
are its chars.  But as Yuri pointed out, the
chars themselves aren't shared, because they
aren't sharable: they aren't references.

Strings can also have properties.  We sometimes
say that it's the characters that have the
properties, but really it's that the properties
are attached to the characters in the string or
buffer - the properties are associated with
string or buffer positions.  The chars themselves
don't really have properties.  The properties are
shared when you copy a string; the chars are not.

This is really more of a natural-language nuance,
about what it means for string elements to be
shared.  You can ignore it, if what I'm saying
just confuses things.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Monday, July 31st, 2023 at 1:36 PM, Drew Adams <drew.adams@oracle.com> wrote:


> > > > A string doesn't share anything because characters are not reference
> > > > values. They are simply copied.
> > > 
> > > Yes and no.
> > > Chars are not shared, but char properties are.
> > > 
> > > (setq foo (propertize "abcd" 'p1 t 'p2 42))
> > > ;; -> #("abcd" 0 4 (p2 42 p1 t))
> > > (setq bar (copy-sequence foo))
> > > ;; -> #("abcd" 0 4 (p1 t p2 42))
> > > (aset foo 1 ?W) ; -> ?W, aka 87
> > > foo ; -> #("aWcd" 0 4 (p2 42 p1 t))
> > > bar ; -> #("abcd" 0 4 (p1 t p2 42))
> > 
> > Ok, meaning that the actual string becomes different, yet changing
> > the a property, changes the property on both foo and bar ?
> 
> 
> No. I didn't change a property. I swapped one
> char for another. The doc says that the arg's
> "elements" are shared. A string's "elements"
> are its chars. But as Yuri pointed out, the
> chars themselves aren't shared, because they
> aren't sharable: they aren't references.

You only changed a character, which is not actually sharable.
But if I go change a property value for foo, I should see the
change also in bar, or not ?
 
> Strings can also have properties. We sometimes
> say that it's the characters that have the
> properties, but really it's that the properties
> are attached to the characters in the string or
> buffer - the properties are associated with
> string or buffer positions. The chars themselves
> don't really have properties. The properties are
> shared when you copy a string; the chars are not.

Meaning that I can make a copy of a string just to have 
the same properties (e.g, colour).
 
> This is really more of a natural-language nuance,
> about what it means for string elements to be
> shared. You can ignore it, if what I'm saying
> just confuses things.

Not too confusing, but required some attention.

Currently I am only interested in the actual characters
in my implementation where properties are not important.

Yet in my permute implementation I have seen that whether
I just use string or (copy-sequence string) does make a huge
difference.  Quite difficult to understand what's going on.

bug#64960: Documentation for copy-sequence

[Eli Zaretskii]

> Date: Sun, 30 Jul 2023 19:20:45 +0000
> From: uzibalqa <uzibalqa@proton.me>
> Cc: 64960@debbugs.gnu.org
> 
> > As the doc string says: the elements are not copied. You get a new
> > sequence whose elements are shared with the original one.
> 
> So it returns a copy but elements are not copied.  So what happens exactly ?
> You get a reference to the original ?

Yes.

> When I modify the copy, the original remains intact.

No, if you modify an element of the copy, the corresponding element of
the original is also changed.  That's what "shared" means.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Monday, July 31st, 2023 at 2:21 PM, Eli Zaretskii <eliz@gnu.org> wrote:


> > Date: Sun, 30 Jul 2023 19:20:45 +0000
> > From: uzibalqa uzibalqa@proton.me
> > Cc: 64960@debbugs.gnu.org
> > 
> > > As the doc string says: the elements are not copied. You get a new
> > > sequence whose elements are shared with the original one.
> > 
> > So it returns a copy but elements are not copied. So what happens exactly ?
> > You get a reference to the original ?
> 
> 
> Yes.
> 
> > When I modify the copy, the original remains intact.
> 
> 
> No, if you modify an element of the copy, the corresponding element of
> the original is also changed. That's what "shared" means.

Except for strings

bug#64960: Documentation for copy-sequence

[Michael Heerdegen]

uzibalqa via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

> > > When I modify the copy, the original remains intact.
> >
> >
> > No, if you modify an element of the copy, the corresponding element of
> > the original is also changed. That's what "shared" means.
>
> Except for strings

It is irrelevant what happens when you modify elements of a copied
string because it is impossible.  The statement is simply not applicable
to strings.  That's why the docstring only speaks of "list, vector or
record".

Note that substituting a character in a string is not the same as
modifying the character.  You are substituting a sequence element with
another one and not modifying an element in that case.

The same is true for the list (1 2 3) for example.  Exactly the same
situation as for a string: You can replace the number 2 in a copy with
another one but you can't modify the number 2 in the list.  Numbers and
characters are not mutable.

Michael.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Monday, July 31st, 2023 at 5:24 PM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> uzibalqa via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" bug-gnu-emacs@gnu.org writes:
> 
> > > > When I modify the copy, the original remains intact.
> > > 
> > > No, if you modify an element of the copy, the corresponding element of
> > > the original is also changed. That's what "shared" means.
> > 
> > Except for strings
> 
> 
> It is irrelevant what happens when you modify elements of a copied
> string because it is impossible. The statement is simply not applicable
> to strings. That's why the docstring only speaks of "list, vector or
> record".

> Note that substituting a character in a string is not the same as
> modifying the character. You are substituting a sequence element with
> another one and not modifying an element in that case.

That I understand.  I am substituting, but still one gets a different string
nevertheless.
 
> The same is true for the list (1 2 3) for example. Exactly the same
> situation as for a string: You can replace the number 2 in a copy with
> another one but you can't modify the number 2 in the list. Numbers and
> characters are not mutable.

This is the difficult part.  You have a copy of a list and you can swap
elements but not make new ones.  So what you share is the address, where
element 2 say uses the address of element 3.

All this copy-sequence is then quite restrictive in its capabilities.
It does not allow much changes.   
 
> Michael.
>

bug#64960: Documentation for copy-sequence

[Drew Adams]

> > > > When I modify the copy, the original remains intact.
> > >
> > > No, if you modify an element of the copy, the corresponding element of
> > > the original is also changed. That's what "shared" means.
> >
> > Except for strings
> 
> It is irrelevant what happens when you modify elements of a copied
> string because it is impossible.  The statement is simply not applicable
> to strings.  That's why the docstring only speaks of "list, vector or
> record".
> 
> Note that substituting a character in a string is not the same as
> modifying the character.  You are substituting a sequence element with
> another one and not modifying an element in that case.
> 
> The same is true for the list (1 2 3) for example.  Exactly the same
> situation as for a string: You can replace the number 2 in a copy with
> another one but you can't modify the number 2 in the list.  Numbers and
> characters are not mutable.

Well put.

bug#64960: Documentation for copy-sequence

[Michael Heerdegen]

uzibalqa <uzibalqa@proton.me> writes:

> > The same is true for the list (1 2 3) for example. Exactly the same
> > situation as for a string: You can replace the number 2 in a copy with
> > another one but you can't modify the number 2 in the list. Numbers and
> > characters are not mutable.
>
> This is the difficult part.  You have a copy of a list and you can swap
> elements but not make new ones.  So what you share is the address, where
> element 2 say uses the address of element 3.
>
> All this copy-sequence is then quite restrictive in its capabilities.
> It does not allow much changes.

I must admit that I don't understand this answer.  What does "can't make
new elements" mean?  "Does not allow changes"...you lost me here.

Michael.

bug#64960: Documentation for copy-sequence

[Michael Heerdegen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> I must admit that I don't understand this answer.  What does "can't make
> new elements" mean?  "Does not allow changes"...you lost me here.

We seem to have finished this discussion, and I think all questions have
been answered.  Is there anything, from your side, that you expect we
should do?


TIA,

Michael.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Sunday, August 13th, 2023 at 4:27 PM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Michael Heerdegen michael_heerdegen@web.de writes:
> 
> > I must admit that I don't understand this answer. What does "can't make
> > new elements" mean? "Does not allow changes"...you lost me here.
> 
> 
> We seem to have finished this discussion, and I think all questions have
> been answered. Is there anything, from your side, that you expect we
> should do?

Although I understand what it does, I om not sure if it would benefit
about some of the details we discussed.
 
> TIA,
> 
> Michael.

bug#64960: Documentation for copy-sequence

[Michael Heerdegen]

uzibalqa <uzibalqa@proton.me> writes:

> Although I understand what it does, I om not sure if it would benefit
> about some of the details we discussed.

What in particular?  A lot of the stuff discussed is a direct
consequence of the copy being a new sequence object whose elements have
not been copied.  The manual tries to describe some implications.

Or should we try to find a better wording (to make more clear that
"modify" doesn't mean "replace") - for what part(s)?  What concretely
would have helped you to understand that part of the manual better?

What parts of the documentation have you read so far?


Thx,

Michael.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Sent with Proton Mail secure email.

------- Original Message -------
On Tuesday, August 15th, 2023 at 11:46 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> uzibalqa uzibalqa@proton.me writes:
> 
> > Although I understand what it does, I om not sure if it would benefit
> > about some of the details we discussed.
> 
> 
> What in particular? A lot of the stuff discussed is a direct
> consequence of the copy being a new sequence object whose elements have
> not been copied. The manual tries to describe some implications.
> 
> Or should we try to find a better wording (to make more clear that
> "modify" doesn't mean "replace") - for what part(s)? What concretely
> would have helped you to understand that part of the manual better?

I found the following is mostly targeted at experienced users.

"The elements of a list, vector or record are not copied; they are
shared with the original."
 
Adding additional wording that it means that not everything is actually copied. 
Some aspects are actually reference values.  Meaning that if you change the
copied sequence, you could inadvertently change the original sequence.

> What parts of the documentation have you read so far?
> 
> 
> Thx,
> 
> Michael.
>

bug#64960: Documentation for copy-sequence

[Michael Heerdegen]

uzibalqa via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

> "The elements of a list, vector or record are not copied; they are
> shared with the original."
>
> Adding additional wording that it means that not everything is
> actually copied.
> Some aspects are actually reference values.  Meaning that if you change the
> copied sequence, you could inadvertently change the original sequence.

That's the normal behavior in a Lisp, so this belongs into the manual.
After reading (info "(elisp) Sequence Functions") (where this function
is introduced) I think, as far as I understand, that that page tries to
explain this aspect you mention thoroughly.

Michael.

bug#64960: Documentation for copy-sequence

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Sent with Proton Mail secure email.

------- Original Message -------
On Wednesday, August 16th, 2023 at 11:28 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> uzibalqa via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" bug-gnu-emacs@gnu.org writes:
> 
> > "The elements of a list, vector or record are not copied; they are
> > shared with the original."
> > 
> > Adding additional wording that it means that not everything is
> > actually copied.
> > Some aspects are actually reference values. Meaning that if you change the
> > copied sequence, you could inadvertently change the original sequence.
> 
> 
> That's the normal behavior in a Lisp, so this belongs into the manual.
> After reading (info "(elisp) Sequence Functions") (where this function
> is introduced) I think, as far as I understand, that that page tries to
> explain this aspect you mention thoroughly. - Michael.

Is it not customary to include any cross references to the relevant parts
of the manual.  The help using 'C-h f' would benefit if there could be
some links that get you to the relevant part of the manual directly.

bug#64960: Documentation for copy-sequence

[Stefan Kangas]

Version: 29.2

uzibalqa <uzibalqa@proton.me> writes:

> Is it not customary to include any cross references to the relevant parts
> of the manual.  The help using 'C-h f' would benefit if there could be
> some links that get you to the relevant part of the manual directly.

Such a cross-reference was added in commit a8c8a4e3680d, so I'm closing
this bug.