47.5 Mapping Over Extents

The most basic and general function for mapping over extents is called map-extents. You should read through the definition of this function to familiarize yourself with the concepts and optional arguments involved. However, in practice you may find it more convenient to use the function mapcar-extents or to create a loop using the before argument to extent-at (see Finding Extents).

Function: map-extents function &optional object from to maparg flags property value

This function maps function over the extents which overlap a region in object. object is normally a buffer or string but could be an extent (see below). The region is normally bounded by [from, to) (i.e. the beginning of the region is closed and the end of the region is open), but this can be changed with the flags argument (see below for a complete discussion).

function is called with the arguments (extent, maparg). The arguments object, from, to, maparg, and flags are all optional and default to the current buffer, the beginning of object, the end of object, nil, and nil, respectively. map-extents returns the first non-nil result produced by function, and no more calls to function are made after it returns non-nil.

If object is an extent, from and to default to the extent’s endpoints, and the mapping omits that extent and its predecessors. This feature supports restarting a loop based on map-extents. Note: object must be attached to a buffer or string, and the mapping is done over that buffer or string.

An extent overlaps the region if there is any point in the extent that is also in the region. (For the purpose of overlap, zero-length extents and regions are treated as closed on both ends regardless of their endpoints’ specified open/closedness.) Note that the endpoints of an extent or region are considered to be in that extent or region if and only if the corresponding end is closed. For example, the extent [5,7] overlaps the region [2,5] because 5 is in both the extent and the region. However, (5,7] does not overlap [2,5] because 5 is not in the extent, and neither [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the region.

The optional flags can be a symbol or a list of one or more symbols, modifying the behavior of map-extents. Allowed symbols are:

end-closed

The region’s end is closed.

start-open

The region’s start is open.

all-extents-closed

Treat all extents as closed on both ends for the purpose of determining whether they overlap the region, irrespective of their actual open- or closedness.

all-extents-open

Treat all extents as open on both ends.

all-extents-closed-open

Treat all extents as start-closed, end-open.

all-extents-open-closed

Treat all extents as start-open, end-closed.

start-in-region

In addition to the above conditions for extent overlap, the extent’s start position must lie within the specified region. Note that, for this condition, open start positions are treated as if 0.5 was added to the endpoint’s value, and open end positions are treated as if 0.5 was subtracted from the endpoint’s value.

end-in-region

The extent’s end position must lie within the region.

start-and-end-in-region

Both the extent’s start and end positions must lie within the region.

start-or-end-in-region

Either the extent’s start or end position must lie within the region.

negate-in-region

The condition specified by a *-in-region flag must not hold for the extent to be considered.

At most one of all-extents-closed, all-extents-open, all-extents-closed-open, and all-extents-open-closed may be specified.

At most one of start-in-region, end-in-region, start-and-end-in-region, and start-or-end-in-region may be specified.

If optional arg property is non-nil, only extents with that property set on them will be visited. If optional arg value is non-nil, only extents whose value for that property is eq to value will be visited.

If you want to map over extents and accumulate a list of results, the following function may be more convenient than map-extents.

Function: mapcar-extents function &optional predicate buffer-or-string from to flags property value

This function applies function to all extents which overlap a region in buffer-or-string. The region is delimited by from and to. function is called with one argument, the extent. A list of the values returned by function is returned. An optional predicate may be used to further limit the extents over which function is mapped. The optional arguments flags, property, and value may also be used to control the extents passed to predicate or function, and have the same meaning as in map-extents.

Function: map-extent-children function &optional object from to maparg flags property value

This function is similar to map-extents, but differs in that:

• It only visits extents which start in the given region.
• After visiting an extent e, it skips all other extents which start inside e but end before e’s end.

Thus, this function may be used to walk a tree of extents in a buffer:

(defun walk-extents (buffer &optional ignore)
  (map-extent-children 'walk-extents buffer))

Function: extent-in-region-p extent &optional from to flags

This function returns t if map-extents would visit extent if called with the given arguments.