XPointer xpointer() Scheme

4.4.1 Definition of Point Location

[Definition: A location of type point is defined in terms of two data items:] The first is the [Definition: container node, which is that node that directly contains the point.] For example, a point between two adjacent characters within a text node will be the text node. The second is the [Definition: index], which is a non-negative integer that represents the offset of the point among the child nodes or the character content of the container node (each node type can have only one or the other). An index of zero indicates the point before any child nodes or contained characters, and a non-zero index n indicates the point immediately after the nth child node or character.

As defined, points are sufficient to identify the location preceding or following any individual character, or preceding or following any node in the data set constructed from an XML document or external parsed entity.

Given this definition, two points are necessarily identical if they have the same container node and index.

A point location does not have an expanded-name.

The string-value of a point location is empty.

The axes of a point location are defined as follows:

• The child, descendant, preceding-sibling, following-sibling, preceding, following, attribute, and namespace axes are empty.

• The descendant-or-self axis contains the point itself.

• The self axis contains the point itself.

• The parent axis contains the point's container node.

• The ancestor axis contains the point's container node and its ancestors.

• The ancestor-or-self axis contains the point itself, the point's container node, and its ancestors.

4.4.2 Definition of Range Location

A location of type [Definition: range is defined by two points], a [Definition: start point] and an [Definition: end point]. A range represents all of the XML structure and content between the start point and end point. This is distinct from any list of nodes and/or characters, in part because some nodes might be only partly included. The start point and end point of a range must be in the same document or external parsed entity. The start point must not appear after the end point in document order (see 4.4.5 Document order).

[Definition: A range whose start point and end point are equal is a collapsed range.]

If the container node of one point of a range is a node of a type other than element, text, or root, the container node of the other point of the range must be the same node. For example, it is allowed to specify a range from immediately before a processing instruction to the end of an element, but not to specify a range from text inside a processing instruction to text outside it.

A range location does not have an expanded-name.

The string-value of a range location consists of the characters that are in text nodes and that are between the start point and end point of the range.

The axes of a range location are identical to the axes of its start point. For example, the parent axis of a range contains the parent of the start point of the range.

4.4.3 Covering Ranges for All Location Types

[Definition: A covering range is a range that wholly and exactly encompasses a location. The covering range can be identified by applying the covering-range function to any location. The equivalent covering range for each type of location is defined as follows:]

• For a range location, the covering range is identical to the range (note that as in DOM [DOM2], although ranges are well-defined within all node types, ranges may not extend from inside the boundaries of namespace, attribute, comment, or processing instruction nodes to outside, or from outside to inside).

• For a point location, the start and end points of the covering range are the point itself.

• For a node location that is an element, text, comment, or processing instruction node, the container node of the start point and of the end point of the covering range are both the parent of the identified node; the index of the start point of the covering range is the number of preceding sibling nodes of the location; and the index of the end point is one greater than the index of the start point.

• For a node location that is the root node, the container node of the start point and end point of the covering range are both the root node; the index of the start point of the covering range is 0; and the index of the end point of the covering range is the number of children of the root location.

• For a node location that is an attribute or namespace node, the container node of the start point and end point of the covering range is the attribute or namespace node itself; the index of the start point of the covering range is 0; and the index of the end point of the covering range is the length of the string-value of the attribute or namespace node.

4.4.4 Tests for point and range Locations

The xpointer() scheme extends the XPath production for NodeType... by adding items for the point and range location types. The production (number 38 in XPath) becomes as follows:

NodeType

This definition allows NodeTests to select locations of type point and range from a location-set that might include locations of many types.

4.4.5 Document order

XPointer must be able to represent locations that are entire element nodes, like XPath; but also locations that are not. For example, an edit insertion point does not correspond to any whole node, but rather to a zero-size location, such as the point immediately preceding a character of text within a text node or between two adjacent element nodes. Similarly, typical drag-selections in various applications correspond to ranges, not nodes.

As in DOM 2: Range[DOM2], a point is determined by the node that contains it, and the offset of the point within that node. A range is determined by its starting and ending points.

The appendix "On points and ranges" provides a simple notation that is similar in syntax to the XPointer element() scheme, but that is not limited to identifying whole elements. That notation clarifies the definition of document ordering given here and has useful additional properties, but ordering can be implemented using that or any other representation.

The diagram below shows the numbering of nodes and points in a graphic representation of an XML Information Set.

Figure 1: Numbering of nodes and points

For example,

• point(1.0) is just inside the beginning of the p element.

• point(1.2) is between the end of the em element and the following text node (which contains "world.").

• point(.0) immediately precedes the root node.

• point(1/2/1.1) immediately following the "b" in the middle text node.

Intuitively, points are ordered largely as one would expect from a pre-order traversal of the document, or the XML stream order.

More formally, any two document locations that are comparable, regardless of which type(s) they are, can be compared by comparing their covering ranges. A comparison of ranges is defined purely by a sequence of comparisons of their starting and ending points. Because all comparisons thus reduce to comparisons of points, point comparison is defined first below. The sequence of point comparisons required to compare two ranges is defined second, and is sufficient for comparing any locations that can be compared.

Because text nodes are not explicitly represented in XML documents, the point immediately before (or after) a text node occurs at the same place in an XML source document as the point immediately before (or after) that text node's first (or last) character. This specification defines those locations as distinct; they do not compare as equal. For example, point(1.2) is not equal to point(1/3.0).

Because the attribute and namespace nodes of a given element node are unordered, it is illegal to compare them in certain ways, and the result of such an attempted comparison is undefined. Specifically:

• Points within different attribute and/or namespace nodes of the same container node may not be compared.

• A point within an attribute or namespace node may not be compared to the location of its container node.

• A point within an attribute or namespace node, however, may be compared to any node other than its parent node or to any point within any node other than its parent node. In such comparisons, the point is ordered as its parent node would be.

• Two points within the same attribute or namespace node may be compared, and are compared by their offsets just as are points within any other node.

Points within the same container node compare as do the values of their respective offsets.

Points within different nodes cannot be correctly ordered merely by comparing the order of their container nodes. For example, the later point could be late in a large node N, while the earlier point could be within an earlier child M of N. In that case node N is before M (because it started earlier), and so merely comparing M and N would produce the incorrect result.

To compare any comparable points P1 and P2:

point(.0) compares as before any other point; point(.1) compares as after any other point.

1. Define Node1 as the child sequence of the node directly containing point P1, and Node2 as the child sequence of the node directly containing point P2.

2. Define Offset1 as the offset of point P1 within the node identified by Node1, and Offset2 as the offset of point P2 within the node identified by Node2.

3. Beginning at the uppermost end of Node1 and Node2 (typically both 1 for the XML document element), compare corresponding components of the two paths and discard all such pairs that are equal.

4. If a further component(s) is available from neitherNode1 nor Node2, the points are directly within the same containing node, and are ordered simply by their respective offsets.

5. If a further component(s) is available from bothNode1 and Node2, then the node whose next component value is greater represents the point that is later in document order.

6. If a further component(s) is available for only Node1, then P1 is within some descendant of the node in which P2 directly occurs. Thus it is necessary to determine the position of Offset2 relative to the ancestor of P1 that is at the same level (that is a child of Node2). To do this, compare Offset2 to the first of the further components for Node1. If Offset2 is greater than or equal, then P2 follows P1 in document order; otherwise it precedes P1.

7. If a further component(s) is available for only Node2, compare Offset1 to the first of the further components for Node2. If Offset1 is greater than or equal, then P1 follows P2 in document order; otherwise it precedes P2.

Two ranges R1 and R2 are ordered using the following sequence of comparisons of their starting and ending points (these definitions avoid circularity because the definition of point ordering given above does not involve casting the compared points to their equivalent collapsed ranges):

If the start point of R1 is not equal to the start point of R2, then the ranges are ordered as their respective start points are ordered. That is, if R1 starts before R2 it is before R2, and if R1 starts after R2 it is after R2.

If the start point of R1 is equal to the start point of R2, then the ranges are ordered as their respective end points are ordered. That is, if R1 and R2 start at the same point, then: if R1 ends before R2 it is before R2; if R1 and R2 end at the same point R1 is equal to R2; and if R1 ends after R2 it is after R2.

Thus, R1 and R2 are equal if and only if their respective start points and end points are equal.

Comparisons between any two types of locations (point vs. node, etc.) must produce the same results as obtained through converting all comparands to their equivalent ranges and comparing those ranges.

This algorithm yields the correct results; however, implementations need not use this specific algorithm to compare point locations. They may use any algorithm that produces the same results.

4.5.1 range-to Function

location-setrange-to(location-set)

For each location in the context, range-to returns a range. The start point of the range is the start point of the context location (as determined by the start-point function), and the end point of the range is the end point (as determined by the end-point function) of the location found by evaluating the expression argument with respect to that context location.

The change made to the XPath syntax to support the range-to construct corresponds to a single addition to the Step production of the [XPath] specification. The original production is as follows:

[4] Step ::= AxisSpecifier NodeTest Predicate* | AbbreviatedStep

The version in the xpointer() scheme is as follows:

[4xptr] Step ::= AxisSpecifier NodeTest Predicate* | AbbreviatedStep | 'range-to' '(' Expr ')' Predicate*

This change is a single exception for the range-to function. It is not a generic change and is not extensible to other functions. The modified production expresses that a range computation must be made for each of the locations in the current location list.

As an example of using the range-to function, the following pointer part locates the range from the start point of the element with ID "chap1" to the end point of the element with ID "chap2".

xpointer(id("chap1")/range-to(id("chap2")))

As another example, imagine a document that uses empty elements (such as <REVST/> for revision start and <REVEND/> for revision end) to mark the boundaries of edits. The following pointer part would select, for each revision, a range starting at the beginning of the REVST element and ending at the end of the next REVEND element:

xpointer(descendant::REVST/range-to(following::REVEND[1]))

4.5.2 string-range Function

location-setstring-range(location-set, string, number?, number?)

For each location in the location-set argument, string-range returns a set of ranges determined by searching the string-value of the location for substrings that match the string argument. An empty string is defined to match before each character of the string-value and after the final character. White space in a string is matched literally, with no normalization except that provided by XML for line ends and attribute values. Each non-overlapping match can contribute a range to the resulting location set.

The third argument gives the position of the first character to be in the resulting range, relative to the start of the match. The default value is 1, which makes the range start immediately before the first character of the matched sub-string. The fourth argument gives the number of characters in the range; the default is that the range extends to the end of the matched string. Thus, both the start point and end point of each range returned by the string-range function will be within text nodes.

Element boundaries, as well as entire embedded nodes such as processing instructions and comments, are ignored as specified by the definition of string-value in [XPath].

For any particular location, if the string argument is not found in the string-value of the location, or if the third and fourth argument indicates a range that is wholly beyond the beginning or end of the document or entity, then no range is added to the result for that match.

The start and end points of the range-locations in the returned location-set will all be character-points.

For example, the following expression returns a range that selects the 17th of those "Thomas Pynchon" strings appearing in a title element:

string-range(//title,"Thomas Pynchon")[17]

As another example, the following expression returns a collapsed range whose points immediately precede the letter "P" (8 from the start of the string) in the third of those "Thomas Pynchon" strings appearing in a P element:

string-range(//P,"Thomas Pynchon",8,0)[3]

Alternatively this could be specified as follows:

string-range(string-range(//P,"Thomas Pynchon")[3],"P",1,0)

String-values are "views" into only the string content of a document or entity; they do not retain the structural context of any non-text nodes interspersed with the text. Because the string-range function operates on a string-value, markup that intervenes in the middle of a string does not prevent a match. (Note that for this reason, a string-range match is a range describing the relevant substring of the string-value, not necessarily a contiguous string in a single text node in the document.) For example, if the 17th occurrence of "Thomas Pynchon" had some inline markup in it as follows, it would not change the string identified by the XPointer processor:

Thomas <em>Pyn</em>chon

The following expression selects the fifth of those exclamation marks appearing in any text node in the document and the character immediately following that exclamation mark:

string-range(/,"!",1,2)[5]

Although these examples locate ranges via text in the string-values of elements, string-range is useful for locating ranges that are wholly enclosed in other node types as well, such as attributes, processing instructions, and comments.

4.5.3 Additional Range-Related Functions

The following functions are related to ranges.

4.5.4 here Function

location-sethere()

The here function is meaningful only when the expression being interpreted occurs in an XML document or external parsed entity; otherwise the pointer part in which the here function appears fails. When in an XML context, the here function returns a location-set with a single member. There are two possibilities for the location returned:

• If the expression being evaluated appears in a text node inside an element node, the location returned is the element node.

• Otherwise, the location returned is the node that directly contains the expression being evaluated.

In the following example, the here function appears inside an expression that is in an attribute node. The expression as a whole, then, returns the slide element just preceding the slide element that most directly contains the attribute node in question.

<button xlink:type="simple" xlink:href="#xpointer(here()/ancestor::slide[1]/preceding::slide[1])"> Previous </button>

4.5.5 origin Function

location-setorigin()

The origin() function is meaningful only when the expression is being processed in response to traversal of a link expressed in an XML document. The origin function enables addressing relative to third-party and inbound links such as defined in the XLink Recommendation. This allows expressions to express relative locations when links do not reside directly at one of their endpoints. The function returns a location-set with a single member, which locates the element from which a user or program initiated traversal of the link. (See [XLink] for information about traversal.)

It is an error to use origin in the fragment identifier portion of a URI reference where a URI is also provided and identifies a resource different from the resource from which traversal was initiated, or in a situation where traversal is not occurring.