plist-put modification by side effect

plist-put modification by side effect

[Dan Davison]

,----[C-h f plist-put]
| plist-put is a built-in function in `C source code'.
| (plist-put plist prop val)
| 
| Change value in plist of prop to val.
| plist is a property list, which is a list of the form
| (PROP1 VALUE1 PROP2 VALUE2 ...).  prop is a symbol and val is any object.
| If prop is already a property on the list, its value is set to val,
| otherwise the new prop val pair is added.  The new plist is returned;
| use `(setq x (plist-put x prop val))' to be sure to use the new value.
| The plist is modified by side effects.
| 
`----

I don't get this. It says the plist is altered by side effects. So
what's with the "but just to be extra careful use (setq ...)"  advice?
I think I've seen a similar statemenmt in other docstrings, but I
can't remember which. Is there some subtlety that means you can't
actually rely on the side effect? Surely not?

Thanks,

Dan


-- 
http://www.stats.ox.ac.uk/~davison

Re: plist-put modification by side effect

[Thien-Thi Nguyen]

() Dan Davison <davison@stats.ox.ac.uk>
() Sat, 31 Jan 2009 16:06:30 -0500

   I don't get this. It says the plist is altered by side
   effects. So what's with the "but just to be extra careful
   use (setq ...)"  advice?

If PROP is in PLIST, the natural side-effecting operation is
to splice in the VALUE at the position of the old value.  Ok,
fine.  Now, what if PROP is not in PLIST?  How might you
implement that?  How might you implement that, differently?
How might your design decision surprise the unwary caller?

thi

Re: plist-put modification by side effect

[Dan Davison]

On Sun, Feb 01, 2009 at 12:02:42AM +0100, Thien-Thi Nguyen wrote:
> () Dan Davison <davison@stats.ox.ac.uk>
> () Sat, 31 Jan 2009 16:06:30 -0500
> 
>    I don't get this. It says the plist is altered by side
>    effects. So what's with the "but just to be extra careful
>    use (setq ...)"  advice?
> 
> If PROP is in PLIST, the natural side-effecting operation is
> to splice in the VALUE at the position of the old value.  Ok,
> fine.  Now, what if PROP is not in PLIST?  How might you
> implement that?  How might you implement that, differently?
> How might your design decision surprise the unwary caller?
> 

Thanks Thi and Helmut for your answers.

Let me see if can answer the questions Thi set me. If PROP is not in PLIST,
then I guess the two possibilities you are referring to are 

1. add PROP with value VAL to head of PLIST
2. add PROP with value VAL to tail of PLIST

and only in case 2 will PLIST be altered by side-effect.

So if I've understood this then I think the docstring is inaccurate
since `The PLIST is modified by side effects.' is not necessarily
true. I also think it would be helpful if the docstring spelled things
out more. I'd suggest something like

Change value in PLIST of PROP to VAL.
PLIST is a property list, which is a list of the form (PROP1 VALUE1
PROP2 VALUE2 ...).  PROP is a symbol and VAL is any object.  If PROP
is already a property on the list, its value is set to VAL. Otherwise
the new PROP VAL pair is added; in this case PLIST (if non-nil)
may be modified by side effects, although this cannot be relied
upon. Therefore use `(setq x (plist-put x prop val))' to be sure to
use the new value.

Dan

> thi
> 

-- 
http://www.stats.ox.ac.uk/~davison

Re: plist-put modification by side effect

[Barry Margolin]

In article <mailman.6441.1233508294.26697.help-gnu-emacs@gnu.org>,
 Dan Davison <davison@stats.ox.ac.uk> wrote:

> I want to modify a plist inside a function, in such a way that
> the modifications are available outside the function. Does Thi's
> answer mean that I should use something like nconc and not
> plist-put?

That still won't help for the case where the plist is empty when your 
function is called, because there's nothing to nconc to.

-- 
Barry Margolin, barmar@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***
*** PLEASE don't copy me on replies, I'll read them in the group ***

Re: plist-put modification by side effect

[Thien-Thi Nguyen]

() Dan Davison <davison@stats.ox.ac.uk>
() Sun, 1 Feb 2009 11:23:14 -0500

   So if I've understood this then I think the docstring is inaccurate
   since `The PLIST is modified by side effects.' is not necessarily
   true.

When something is consed onto the head of a list, the list is not modified.

thi

Re: plist-put modification by side effect

[Andreas Politz]

Thien-Thi Nguyen wrote:
> () Dan Davison <davison@stats.ox.ac.uk>
> () Sun, 1 Feb 2009 11:23:14 -0500
> 
>    So if I've understood this then I think the docstring is inaccurate
>    since `The PLIST is modified by side effects.' is not necessarily
>    true.
> 
> When something is consed onto the head of a list, the list is not modified.
> 
> thi
> 
> 

I believe the whole term 'side effect' is a lisp heritage, where it marks a
destructive function, one which _may_ modify it's arguments.
In constrast to 'functional functions' like append etc. So the emphasis is
on 'altering it's argument' and not on 'dont' bother with the return value'.

-ap

Re: plist-put modification by side effect

[Helmut Eller]

* Dan Davison [2009-01-31 22:06+0100] writes:

> ,----[C-h f plist-put]
> | plist-put is a built-in function in `C source code'.
> | (plist-put plist prop val)
> | 
> | Change value in plist of prop to val.
> | plist is a property list, which is a list of the form
> | (PROP1 VALUE1 PROP2 VALUE2 ...).  prop is a symbol and val is any object.
> | If prop is already a property on the list, its value is set to val,
> | otherwise the new prop val pair is added.  The new plist is returned;
> | use `(setq x (plist-put x prop val))' to be sure to use the new value.
> | The plist is modified by side effects.
> | 
> `----
>
> I don't get this. It says the plist is altered by side effects. So
> what's with the "but just to be extra careful use (setq ...)"  advice?
> I think I've seen a similar statemenmt in other docstrings, but I
> can't remember which. Is there some subtlety that means you can't
> actually rely on the side effect? Surely not?

If the list is nil, there is nothing to be modified and plist-put
allocates a new list instead.  In this case you must assign the returned
value.  The same situation occurs with the delete function when the list
would be empty after the removing all elements.

Helmut.