Function: vundo--trim-undo-list

vundo--trim-undo-list is a natively compiled function defined in vundo.el.

Signature

(vundo--trim-undo-list BUFFER CURRENT MOD-LIST)

Documentation

Trim buffer-undo-list in BUFFER according to CURRENT and MOD-LIST.

CURRENT is the current mod, MOD-LIST is the current mod-list.

This function modifies buffer-undo-list of BUFFER.

IMPORTANT Relationship between vundo--move-to-node, vundo--refresh-buffer, vundo--trim-undo-list:

Each vundo command cycle roughly works like this:
1. vundo--refresh-buffer: buffer-undo-list -> mod-list
2. vundo--move-to-node: read mod-list, modify buffer-undo-list
3. vundo--trim-undo-list: trim buffer-undo-list
1. vundo--refresh-buffer: buffer-undo-list -> mod-list
...

We can call vundo--move-to-node multiple times between two vundo--refresh-buffer. But we should only call vundo--trim-undo-list once between two vundo--refresh-buffer. Because if we only trim once, buffer-undo-list either shrinks or expands. But if we trim multiple times after multiple movements, it could happen that the undo-list first shrinks (trimmed) then expands. In that situation we cannot use the INCREMENTAL option in vundo--refresh-buffer anymore.

Also, if you move back-end-forth with ‘vundo--move-to-node’, it might not work: Suppose undo list is [1 2 3], mod-list is [1 2
3], now we move back to 2, undo list becomes [1 2 3 2’], but
before we refresh vundo buffer, mod-list will remain [1 2 3], so there’s no route from 2 to 3 (you can only move back). Once we refresh the buffer and mod-list is updated to [1 2 3 2’], we have a route from 3 to 2 (2’->3).

Source Code

;; Defined in /nix/store/386w2ds6bdh3gcz9k23jssw4cni4lfr2-emacs-packages-deps/share/emacs/site-lisp/elpa/vundo-2.4.0/vundo.el
(defun vundo--trim-undo-list (buffer current mod-list)
  "Trim `buffer-undo-list' in BUFFER according to CURRENT and MOD-LIST.
CURRENT is the current mod, MOD-LIST is the current mod-list.

This function modifies `buffer-undo-list' of BUFFER.

IMPORTANT Relationship between `vundo--move-to-node',
`vundo--refresh-buffer', `vundo--trim-undo-list':

Each vundo command cycle roughly works like this:
1. `vundo--refresh-buffer': `buffer-undo-list' -> mod-list
2. `vundo--move-to-node': read mod-list, modify `buffer-undo-list'
3. `vundo--trim-undo-list': trim `buffer-undo-list'
1. `vundo--refresh-buffer': `buffer-undo-list' -> mod-list
...

We can call `vundo--move-to-node' multiple times between two
`vundo--refresh-buffer'. But we should only call
`vundo--trim-undo-list' once between two `vundo--refresh-buffer'.
Because if we only trim once, `buffer-undo-list' either shrinks
or expands. But if we trim multiple times after multiple
movements, it could happen that the undo-list first
shrinks (trimmed) then expands. In that situation we cannot use
the INCREMENTAL option in `vundo--refresh-buffer' anymore.

Also, if you move back-end-forth with ‘vundo--move-to-node’, it
might not work: Suppose undo list is [1 2 3], mod-list is [1 2
3], now we move back to 2, undo list becomes [1 2 3 2’], but
before we refresh vundo buffer, mod-list will remain [1 2 3], so
there’s no route from 2 to 3 (you can only move back). Once
we refresh the buffer and mod-list is updated to [1 2 3 2’], we
have a route from 3 to 2 (2’->3)."
  (let ((latest-buffer-state-idx
         ;; Among all the MODs that represents a unique buffer
         ;; state, we find the latest one. Because any node
         ;; beyond that one is dispensable.
         (vundo-m-idx
          (vundo--latest-buffer-state mod-list))))
    ;; Find a trim point between latest buffer state and
    ;; current node.
    (when-let ((possible-trim-point
                (cl-loop for node in (vundo--eqv-list-of current)
                         if (>= (vundo-m-idx node)
                                latest-buffer-state-idx)
                         return node
                         finally return nil)))
      (with-current-buffer buffer
        (setq buffer-undo-list
              (vundo-m-undo-list possible-trim-point)))
      (when vundo--message
        (message "Trimmed to: %s"
                 (vundo-m-idx possible-trim-point))))))