'vtable-update-object' can now be called with one argument

It's often necessary to update the representation of a single
object in a table (e.g a struct, whose identity does not change
when its slots'
values are changed).  To do so, now the function may be called
like this:

  (vtable-update-object table object)

Instead of like this:

  (vtable-update-object table object object)

This also documents the behavior of the just-discovered limitation filed
as bug#69837.
* lisp/emacs-lisp/vtable.el (vtable-update-object): Make 'old-object'
argument optional.  (Bug#69666)

* doc/misc/vtable.texi (Interface Functions): Update documentation.

* etc/NEWS: Add news entry.

1 files changed, 10 insertions, 3 deletions

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index a4f2ed29d93..dd5b70cf32f 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -554,12 +554,19 @@ the object after this object; otherwise append to @var{table}.  This
 also updates the displayed table.
 @end defun
 
-@defun vtable-update-object table object old-object
-Change @var{old-object} into @var{object} in @var{table}.  This also
-updates the displayed table.
+@defun vtable-update-object table object &optional old-object
+Update @var{object}'s representation in @var{table}.  Optional argument
+@var{old-object}, if non-@code{nil}, means to replace @var{old-object}
+with @var{object} and redisplay the associated row in the table.  In
+either case, if the existing object is not found in the table (being
+compared with @code{equal}), signal an error.
 
 This has the same effect as calling @code{vtable-remove-object} and
 then @code{vtable-insert-object}, but is more efficient.
+
+Note a limitation: if the table's buffer is not in a visible window, or
+if its window has changed width since it was updated, updating the table
+is not possible, and an error is signaled.
 @end defun
 
 @defun vtable-column table index