diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 464c0badc36..df511c3d896 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1625,6 +1625,7 @@ current buffer. @cindex empty overlay @cindex overlay, empty +@anchor{empty overlays} An overlay whose @var{start} and @var{end} specify the same buffer position is known as @dfn{empty}. A non-empty overlay can become empty if the text between its @var{start} and @var{end} is deleted. @@ -2056,12 +2057,11 @@ line at display-time. @xref{Truncation}. @kindex evaporate @r{(overlay property)} @item evaporate If this property is non-@code{nil}, the overlay is deleted automatically -if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay (@pxref{Managing Overlays, empty overlay}) a -non-@code{nil} @code{evaporate} property, that deletes it immediately. -Note that, unless an overlay has this property, it will not be deleted -when the text between its starting and ending positions is deleted -from the buffer. +if it becomes empty (i.e., if its length becomes zero). If you give an +empty overlay (@pxref{empty overlays}) a non-@code{nil} @code{evaporate} +property, that deletes it immediately. Note that, unless an overlay has +this property, it will not be deleted when the text between its starting +and ending positions is deleted from the buffer. @kindex display-line-numbers-disable @r{(overlay property)} @item display-line-numbers-disable @@ -2103,11 +2103,11 @@ Properties}. @cindex overlays, searching for @defun overlays-at pos &optional sorted -This function returns a list of all the overlays that cover the character at +This function returns a list of all the overlays that contain the character at position @var{pos} in the current buffer. If @var{sorted} is non-@code{nil}, -the list is in decreasing order of priority, otherwise it is in no particular -order. An overlay contains position @var{pos} if it begins at or before -@var{pos}, and ends after @var{pos}. +the returned list is in decreasing order of priority, otherwise it is in no +particular order. An overlay contains the character at @var{pos} if it begins +at or before @var{pos}, and ends after @var{pos}. To illustrate usage, here is a Lisp function that returns a list of the overlays that specify property @var{prop} for the character at point: @@ -2123,16 +2123,36 @@ overlays that specify property @var{prop} for the character at point: (setq overlays (cdr overlays))) found)) @end smallexample + +Empty overlays (@pxref{empty overlays}) do not contain any characters, +so this function does not return them. Use @code{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 (@pxref{Narrowing}) if @var{pos} is outside of +the narrowing. @end defun @defun overlays-in beg end -This function returns a list of the overlays that overlap the region +This function returns a list of the overlays that overlap with the region @var{beg} through @var{end}. An overlay overlaps with a region if it -contains one or more characters in the region; empty overlays -(@pxref{Managing Overlays, empty overlay}) overlap if they are at -@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} -when @var{end} denotes the position at the end of the accessible part -of the buffer. +contains one or more characters between @var{beg} and @var{end}; this +excludes the characters at (i.e.@: after) @var{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 @var{beg}, +strictly between @var{beg} and @var{end} excluding @var{end}, or at +@var{end} when @var{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 +@var{end} you could increment the @var{end} position instead.) + +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 @var{beg} and/or @var{end} are outside of +the narrowing. @end defun @defun next-overlay-change pos diff --git a/etc/NEWS b/etc/NEWS index ea3191680a1..d1585c8309d 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -3814,6 +3814,13 @@ display time or even cause Emacs to hang trying to display such a face. Affected APIs include 'defface', 'set-face-attribute', their callers, and other similar functions. ++++ +Original behavior of 'overlays-in' and 'overlays-at' has been restored. +Before Emacs 29.1, the list of overlays returned by these two functions +included overlays outside of the current narrowing of the buffer. This +behavior has been restored. As result, 'remove-overlays' can now again +remove overlays outside of the narrowing, as it did before Emacs 29.1. + --- ** 'help-setup-xref' now re-enables the major mode of the Help buffer. As a result, in many cases the buffer will be read-only afterwards. diff --git a/src/buffer.c b/src/buffer.c index b1a835b7ac5..b554cf41874 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -3052,18 +3052,20 @@ the normal hook `change-major-mode-hook'. */) /* Find all the overlays in the current buffer that overlap the range [BEG, END). - If EMPTY is true, include empty overlays in that range and also at - END, provided END denotes the position at the end of the accessible - part of the buffer. - - If TRAILING is true, include overlays that begin at END, provided - END denotes the position at the end of the accessible part of the + If EMPTY is true, include empty overlays in that range and also + those at END, provided END denotes the position at the end of the buffer. + If TRAILING is true, include overlays that begin at ZV. + (FIXME: This argument is nowadays effectively ignored, since the code + no longer pays any attention to ZV. We basically rely on the caller + to ensure that TRAILING is only true when END > ZV. This happens, e.g., + when we are called from overlays_at with BEG = ZV and END = ZV + 1.) + Return the number found, and store them in a vector in *VEC_PTR. Store in *LEN_PTR the size allocated for the vector. Store in *NEXT_PTR the next position after POS where an overlay starts, - or ZV if there are no more overlays. + or Z if there are no more overlays after POS. NEXT_PTR may be 0, meaning don't store that info. *VEC_PTR and *LEN_PTR should contain a valid vector and size @@ -3875,9 +3877,12 @@ DEFUN ("overlays-at", Foverlays_at, Soverlays_at, 1, 2, 0, doc: /* Return a list of the overlays that contain the character at POS. If SORTED is non-nil, then sort them by decreasing priority. -Zero-length overlays that start and stop at POS are not included in -the return value. Instead use `overlays-in' if those overlays are of -interest. */) +Zero-length (a.k.a. "empty") overlays that start and stop at POS are not +included in the return value. Use `overlays-in' if empty overlays are of +interest. + +This function can return overlays outside of the current narrowing of +the buffer if POS is outside of the narrowing. */) (Lisp_Object pos, Lisp_Object sorted) { ptrdiff_t len, noverlays; @@ -3916,14 +3921,18 @@ interest. */) DEFUN ("overlays-in", Foverlays_in, Soverlays_in, 2, 2, 0, doc: /* Return a list of the overlays that overlap the region BEG ... END. -Overlap means that at least one character is contained within the overlay -and also contained within the specified region. +Overlap means that at least one character between BEG and END is contained +within the overlay. Note that this excludes the character at (i.e., after) +END. -Empty overlays are included in the result if they are located at BEG, -between BEG and END, or at END provided END denotes the position at the -end of the accessible part of the buffer. +Empty overlays do not contain any characters, so they are included in the +result if they are located at BEG, between BEG and END, or at END provided +END denotes the position at the end of the buffer. -The resulting list of overlays is in an arbitrary unpredictable order. */) +The resulting list of overlays is in an arbitrary unpredictable order. + +This function can return overlays outside of the current narrowing of +the buffer if BEG and/or END are outside of the narrowing. */) (Lisp_Object beg, Lisp_Object end) { ptrdiff_t len, noverlays; diff --git a/test/src/buffer-tests.el b/test/src/buffer-tests.el index f4654e90bce..3fae18011fb 100644 --- a/test/src/buffer-tests.el +++ b/test/src/buffer-tests.el @@ -905,6 +905,7 @@ should evaporate overlays in both." (should-length 1 (overlays-at 10)) (should-length 1 (overlays-at 20)) (should-length 0 (overlays-at (point-max))) + (should-length 1 (overlays-at (1- (point-max)))) (narrow-to-region 10 20) (should-length 1 (overlays-at (point-min))) (should-length 1 (overlays-at 15))