47.3 Extent Endpoints

Every extent has a start position and an end position, and logically affects the characters between those positions. Normally the start and end positions must both be valid positions in the extent’s buffer or string. However, both endpoints can be nil, meaning the extent is detached. See Detached Extents.

Whether the extent overlaps its endpoints is governed by its start-open and end-open properties. Insertion of a character at a closed endpoint will expand the extent to include that character; insertion at an open endpoint will not. Similarly, functions such as extent-at that scan over all extents overlapping a particular position will include extents with a closed endpoint at that position, but not extents with an open endpoint.

Note that the start-closed and end-closed properties are equivalent to start-open and end-open with the opposite sense.

Both endpoints can be equal, in which case the extent includes no characters but still exists in the buffer or string. Zero-length extents are used to represent annotations (see Annotations) and can be used as a more powerful form of a marker. Deletion of all the characters in an extent may or may not result in a zero-length extent; this depends on the detachable property (see Detached Extents).

Insertion at the position of a zero-length extent expands the extent if both endpoints are closed; goes before the extent if it has the start-open property; and goes after the extent if it has the end-open property. Zero-length extents with both the start-open and end-open properties are treated as if their starting point were closed.

Deletion of a character on a side of a zero-length extent whose corresponding endpoint is closed causes the extent to be detached if its detachable property is set; if the corresponding endpoint is open, the extent remains in the buffer, moving as necessary.

Extents are ordered within a buffer or string by increasing start position, and then by decreasing end position (this is called the display order).

Function: extent-start-position extent

This function returns the start position of extent.

Function: extent-end-position extent

This function returns the end position of extent.

Function: extent-length extent

This function returns the length of extent in characters. If the extent is detached, this returns 0. If the extent is not detached, this is equivalent to

(- (extent-end-position extent) (extent-start-position extent))

Function: set-extent-endpoints extent start end &optional buffer-or-string

This function sets the start and end position of extent to start and end. If both are nil, this is equivalent to detach-extent.

buffer-or-string specifies the new buffer or string that the extent should be in, and defaults to extent’s buffer or string. (If nil, and extent is in no buffer and no string, it defaults to the current buffer.)

See documentation on detach-extent for a discussion of undo recording.