plist-put: destructive?

[Eric Abrahamsen <eric@ericabrahamsen.net>]

Plists are great, except for setting keys, which isn't great.
Occasionally it annoys me enough to want to try to "do something" about
it.

The docstring for plist-put says we should be using:

(setq some-plist (plist-put some-plist :prop val))

To be sure of modifying the list correctly. But all my experiments have
shown that a plain plist-put does modify the original list, and
everything works as expected without re-assigning to the original
variable.

So what's the ambiguity? Are there circumstances where a simple
plist-put isn't going to modify the original plist?

I tried this:

(gv-define-simple-setter plist-get plist-put)

Which allows this to work:

(setf (plist-get some-plist :prop) val)

That's hardly less verbose than the setq re-assignment, but I suppose it
would allow for a plist to be used in cl-letf, or for a custom macro
like:

(with-plist-props ((prop1 :prop1) (prop2 :prop2)) some-plist
  ...)

But if plist-put is reliably destructive, I don't suppose any of that is
really necessary.

Can we rely on plist-put?

Thanks,
Eric