47.4 Finding Extents

The following functions provide a simple way of determining the extents in a buffer or string. A number of more sophisticated primitives for mapping over the extents in a range of a buffer or string are also provided (see Mapping Over Extents). When reading through this section, keep in mind the way that extents are ordered (see Extent Endpoints).

Function: extent-list &optional buffer-or-string from to flags property value

This function returns a list of the extents in buffer-or-string. buffer-or-string defaults to the current buffer if omitted. from and to can be used to limit the range over which extents are returned; if omitted, all extents in the buffer or string are returned.

More specifically, if a range is specified using from and to, only extents that overlap the range (i.e. begin or end inside of the range) are included in the list. from and to default to the beginning and end of buffer-or-string, respectively.

flags controls how end cases are treated. For a discussion of this, and exactly what “overlap” means, see map-extents.

The optional arguments property and value can be used to further restrict which extents are returned. They have the same meaning as for map-extents.

If you want to map a function over the extents in a buffer or string, consider using map-extents or mapcar-extents instead.

See also the function extents-at.

Functions that create extents must be prepared for the possibility that there are other extents in the same area, created by other functions. To deal with this, functions typically mark their own extents by setting a particular property on them. The following function makes it easier to locate those extents.

Function: extent-at pos &optional object property before at-flag

This function finds the “smallest” extent (i.e., the last one in the display order) at (i.e., overlapping) pos in object (a buffer or string) having property set. object defaults to the current buffer. property defaults to nil, meaning that any extent will do. Returns nil if there is no matching extent at pos. If the fourth argument before is not nil, it must be an extent; any returned extent will precede that extent. This feature allows extent-at to be used by a loop over extents.

at-flag controls how end cases are handled (i.e. what “at” really means), and should be one of:

nil

after

An extent is at pos if it covers the character after pos. This is consistent with the way that text properties work.

before

An extent is at pos if it covers the character before pos.

at

An extent is at pos if it overlaps or abuts pos. This includes all zero-length extents at pos.

Note that in all cases, the start-openness and end-openness of the extents considered is ignored. If you want to pay attention to those properties, you should use map-extents, which gives you more control.

The following low-level functions are provided for explicitly traversing the extents in a buffer according to the display order. These functions are mostly intended for debugging—in normal operation, you should probably use mapcar-extents or map-extents, or loop using the before argument to extent-at, rather than creating a loop using next-extent.

Function: next-extent extent

Given an extent extent, this function returns the next extent in the buffer or string’s display order. If extent is a buffer or string, this returns the first extent in the buffer or string.

Function: previous-extent extent

Given an extent extent, this function returns the previous extent in the buffer or string’s display order. If extent is a buffer or string, this returns the last extent in the buffer or string.