Hi Adam, Eli,

Here's my first attempt at fixing this bug and generally making
`vtable-insert-object` more versatile (see attachment).

A few questions / comments:

- Is this the right place to send this patch? Or should it go to emacs-devel?

- There are quite a few combinations of LOCATION and BEFORE to handle, which may
  make the code a bit hard to follow. A possible alternative would be to define
  some internal helper functions, `vtable--insert-before` and
  `vtable--insert-after`. You guys be the judge. (I added a few comments to
  hopefully make it clearer)

- The patch also updates the documentation. Do check the style, though, my
  writing usually isn't so great.

- I'm sure I made all sorts of mistakes with the commit message.

- I don't know if this change warrants a NEWS entry. It's not really
  user-facing, so I didn't add one.

- The current implementation of vtable-insert-object has a bug: it puts the
  object in the right location in the object list and the cache, but not in the
  buffer. This patch also fixes this bug.

- I don't know how to write a non-interactive test for my changes, because
  `vtable-insert-object` only works if the vtable is being displayed in a
  buffer. So instead I wrote an interactive function to test all possible
  combinations of LOCATION and BEFORE:

```emacs-lisp
(defun test-vtable-insert-object-interactive ()
  "Test `vtable-insert-object'."
  (interactive)
  (let ((buffer (get-buffer-create " *vtable-test*")))
    (pop-to-buffer buffer)
    (erase-buffer)
    (let* ((object1 '("Foo" 3))
           (object2 '("Gazonk" 8))
           (table (make-vtable
                   :columns '("Name" (:name "Rank" :width 5))
                   :objects (list object1 object2))))
      (mapc (lambda (args)
              (pcase-let ((`(,object ,location ,before) args))
                (if (y-or-n-p (format "Update table with location = %s and before = %s?" location before))
                    (vtable-insert-object table object location before))))
            `( ; Some correct inputs.
              ;; object    location        before
              (("Fizz" 4)  ,object1        nil)
              (("Bop"  7)  ,object2        t)
              (("Zat"  5)  2               nil)
              (("Dib"  6)  3               t)
              (("Wup"  9)  nil             nil)
              (("Quam" 2)  nil             t)
              ;; And some faulty inputs.
              (("Yat"  1)  -1              nil) ; non-existing index, `before' is ignored.
              (("Vop"  10) 100             t)   ; non-existing index, `before' is ignored.
              (("Jib"  11) ("Bleh"  0)     nil) ; non-existing object.
              (("Nix"  0)  ("Ugh"   0)     t)   ; non-existing object.
              ))
      (if (y-or-n-p "Regenerate table?")
          (vtable-revert)))))
``` 

The final table should have the "Rank" column sorted in ascending order (0-11).
Regenerating the table should not change it.

-- 
Joost Kremers
Life has its moments