42.9.3 Searching for Overlays ¶

Function: overlays-at pos &optional sorted ¶

This function returns a list of all the overlays that contain the character at position pos in the current buffer. If sorted is non-nil, the returned list is in decreasing order of priority, otherwise it is in no particular order. An overlay contains the character at pos if it begins at or before pos, and ends after pos.

To illustrate usage, here is a Lisp function that returns a list of the overlays that specify property prop for the character at point:

(defun find-overlays-specifying (prop)
  (let ((overlays (overlays-at (point)))
        found)
    (while overlays
      (let ((overlay (car overlays)))
        (if (overlay-get overlay prop)
            (setq found (cons overlay found))))
      (setq overlays (cdr overlays)))
    found))

Empty overlays (see empty overlays) do not contain any characters, so this function does not return them. Use overlays-in, described below, instead if empty overlays are of interest.

Note that this function can return overlays outside of the current narrowing of the buffer (see Narrowing) if pos is outside of the narrowing.

Function: overlays-in beg end ¶

This function returns a list of the overlays that overlap with the region beg through end. An overlay overlaps with a region if it contains one or more characters between beg and end; this excludes the characters at (i.e. after) end.

Empty overlays do not contain any characters, so the rule for including them is different: they are said to overlap if they are at beg, strictly between beg and end excluding end, or at end when end denotes the position at the end of the buffer. (The special handling of empty overlays at end of buffer is to allow such overlays to be found and processed. For any other value of end you could increment the end position instead.) Note that if beg and end are the same position, an empty overlay that is at beg is also at end, so this case is somewhat similar to an empty overlay at the end of the buffer.

The order in which the overlays appear in the returned list is unpredictable.

Note that this function can return overlays outside of the current narrowing of the buffer if beg and/or end are outside of the narrowing.

Function: next-overlay-change pos ¶

This function returns the buffer position of the next beginning or end of an overlay, after pos. If there is none, it returns (point-max).

Function: previous-overlay-change pos ¶

This function returns the buffer position of the previous beginning or end of an overlay, before pos. If there is none, it returns (point-min).

As an example, here’s a simplified (and inefficient) version of the primitive function next-single-char-property-change (see Text Property Search Functions). It searches forward from position pos for the next position where the value of a given property prop, as obtained from either overlays or text properties, changes.

(defun next-single-char-property-change (position prop)
  (save-excursion
    (goto-char position)
    (let ((propval (get-char-property (point) prop)))
      (while (and (not (eobp))
                  (eq (get-char-property (point) prop) propval))
        (goto-char (min (next-overlay-change (point))
                        (next-single-property-change (point) prop)))))
    (point)))