(setq x (plist-put x :new 'value))

(setq x (plist-put x :new 'value))

[Mario Lang]

Hi.

The docstring of plist-put reads:

---<snip>---
(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.
---<snip>---

The last two lines seem like they are contradicting each other.
In fact, what plist-put really does if it has to add a new item is
setcdr on the last cons in the list.  I kind of feel the second last line
in the docstring should be removed, since (setq x (plist-put x prop val))
is not necessary.  Or am I missing something?

--- a/src/fns.c
+++ b/src/fns.c
@@ -2005,8 +2005,7 @@ DEFUN ("plist-put", Fplist_put, Splist_put, 3, 3, 0,
 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.
+otherwise the new PROP VAL pair is added.  The new plist is returned.
 The PLIST is modified by side effects.  */)
      (plist, prop, val)
      Lisp_Object plist;

-- 
CYa,
  ⡍⠁⠗⠊⠕

Re: (setq x (plist-put x :new 'value))

[Harald Hanche-Olsen]

+ Mario Lang <mlang@delysid.org>:

> The docstring of plist-put reads:
> 
> ---<snip>---
> [...]
> 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.
> ---<snip>---
> 
> The last two lines seem like they are contradicting each other.
> In fact, what plist-put really does if it has to add a new item is
> setcdr on the last cons in the list.  I kind of feel the second last line
> in the docstring should be removed, since (setq x (plist-put x prop val))
> is not necessary.  Or am I missing something?

Yes: the plist could be empty in the first place.

(setq plist nil)
(plist-put plist :foo :bar) ; => (:foo :bar)
plist ; => nil

- Harald