Function: allout-next-sibling-leap

allout-next-sibling-leap is a byte-compiled function defined in allout.el.gz.

Signature

(allout-next-sibling-leap &optional DEPTH BACKWARD)

Documentation

Like allout-next-sibling, but by direct search for topic at depth.

Traverse at optional DEPTH, or current depth if none specified.

Go backward if optional arg BACKWARD is non-nil.

Return the start point of the new topic if successful, nil otherwise.

Costs more than regular allout-next-sibling for short traversals:

 - we have to check the prior (next, if traveling backwards)
   item to confirm connectivity with the prior topic, and
 - if confirmed, we have to reestablish the allout-recent-* settings with
   some extra navigation
 - if confirmation fails, we have to do more work to recover

It is an increasingly big win when there are many intervening offspring before the next sibling, however, so allout-next-sibling resorts to this if it finds itself in that situation.

Source Code

;; Defined in /usr/src/emacs/lisp/allout.el.gz
;;;_   > allout-next-sibling-leap (&optional depth backward)
(defun allout-next-sibling-leap (&optional depth backward)
  "Like `allout-next-sibling', but by direct search for topic at depth.

Traverse at optional DEPTH, or current depth if none specified.

Go backward if optional arg BACKWARD is non-nil.

Return the start point of the new topic if successful, nil otherwise.

Costs more than regular `allout-next-sibling' for short traversals:

 - we have to check the prior (next, if traveling backwards)
   item to confirm connectivity with the prior topic, and
 - if confirmed, we have to reestablish the allout-recent-* settings with
   some extra navigation
 - if confirmation fails, we have to do more work to recover

It is an increasingly big win when there are many intervening
offspring before the next sibling, however, so
`allout-next-sibling' resorts to this if it finds itself in that
situation."

  (if (if backward (bobp) (eobp))
      nil
    (let* ((start-point (point))
           (target-depth (or depth (allout-depth)))
           (search-whitespace-regexp nil)
           (depth-biased (- target-depth 2))
           (expression (if (<= target-depth 1)
                           allout-depth-one-regexp
                         (format allout-depth-specific-regexp
                                 depth-biased depth-biased)))
           found
           done)
      (while (not done)
        (setq found (save-match-data
                      (if backward
                          (re-search-backward expression nil 'to-limit)
                        (forward-char 1)
                        (re-search-forward expression nil 'to-limit))))
        (if (and found (allout-aberrant-container-p))
            (setq found nil))
        (setq done (or found (if backward (bobp) (eobp)))))
      (if (not found)
          (progn (goto-char start-point)
                 nil)
        ;; rationale: if any intervening items were at a lower depth, we
        ;; would now be on the first offspring at the target depth -- ie,
        ;; the preceding item (per the search direction) must be at a
        ;; lesser depth.  that's all we need to check.
        (if backward (allout-next-heading) (allout-previous-heading))
        (if (< allout-recent-depth target-depth)
            ;; return to start and reestablish allout-recent-*:
            (progn
              (goto-char start-point)
              (allout-depth)
              nil)
          (goto-char found)
          ;; locate cursor and set allout-recent-*:
          (allout-goto-prefix))))))