Positions

A position denotes somewhere in the DOM tree, which can be before or after some node, or between two adjacent nodes.

Positions may become invalid after editing operations. To maintain a valid position across arbitrary editing operations, see Markers.

Types of positions

  • An element denotes the position before the element.
  • (end-pos node) denotes the position at the end of node (after any children).node must be an element.
  • (text-pos node offset) denotes the position before the offset-th character of node. node must be a text-node.
  • nil denotes nowhere. Many position-related functions return nil if requested position does not exist, and propagates nil if they receive nil position as an argument.

    • Node around positions

    The following functions query node around a given position. The return value can be a character or element.If no node is found, nil is returned.

    Function: node-after (marker-or-pos)
    Return the node after MARKER-OR-POS.
    Function: node-before (marker-or-pos)
    Return the node before MARKER-OR-POS.
    Function: node-containing (marker-or-pos)
    Return the node containing MARKER-OR-POS.

    Computing positions

    Basic position functions:

    Function: pos-left (pos &key destructive)
    Return the position to the left of POS.
    If DESTRUCTIVE is non-nil, POS might be mutated.
    Function: pos-right (pos &key destructive)
    Return the position to the right of POS.
    If DESTRUCTIVE is non-nil, POS might be mutated.
    Function: pos-next (pos &key destructive)
    Return the next position of POS in preorder traversal.
    If DESTRUCTIVE is non-nil, POS might be mutated.
    Function: pos-prev (pos &key destructive)
    Return the previous position of POS in preorder traversal.
    If DESTRUCTIVE is non-nil, POS might be mutated.
    Function: pos-up (pos)
    Return the parent position of POS.
    Function: pos-down (pos)
    Return the first child position of POS.
    Function: pos-down-last (pos)
    Return the last child position of POS.

    Iterate until or ensure a position predicate is satisfied: pos-*-until, pos-*-ensure

    Destructive variants: npos-*

    All of the above functions may take and return nil positions without signaling error.

    Comparing positions

    Two positions point to the same location iff they are equalp.

    Additional functions for comparing positions:

    Function: before-p (pos-1 pos-2)
    Test if POS-1 is strictly before POS-2 in preorder traversal.