Using XPointer Points

How do you define a point in the XPointer specification? To do so, you must use two items: a node and an index that can hold a positive integer or zero. The node specifies an origin for the point, and the index indicates how far the point you want is from that origin.

But what should the index be measured in terms ofcharacters in the document or number of nodes? In fact, there are two different types of points, and the index value that you use is measured differently for those types.

Node-Points

When the origin node, also called the container node, of a point can have child nodes (which means it's an element node or the root node), the point is called a node-point.

The index of a node-point is measured in child nodes. Here, the index of a node-point must be equal to or less than the number of child nodes in the origin node. If you use an index of , the point is immediately before any child nodes. An index of 5 locates a point immediately after the fifth child node.

You can use axes with node-points: A node-point's siblings are the children of the container node before or after the node-point. Points don't have any children, however.

Character-Points

If the origin node can't contain any child nodes, only text, the index is measured in characters . Points like these are called character-points.

The index of a character-point must be a positive integer or , and must be less than or equal to the length of the text string in the node. If the index is , the point is immediately before the first character; an index of 5 locates the point immediately after the fifth character. Character-points do not have preceding or following siblings or children.

For example, you can treat <DOCUMENT> as a container node in this document:

 <DOCUMENT>  Hi there! </DOCUMENT> 

In this case, there are nine character-points, one before every character. The character-point at index is right before the first character, H ; the character-point at index 1 is right before the i ; and so on.

In addition, you should note that the XPointer specification collapses all consecutive whitespace into a single space, so four spaces is the same as one when calculating an index for a character-point. Also, you cannot place points inside a start tag, end tag, processing instruction, comment, or any markup.

Point Functions

To create a point, you can use the point() function with a predicate like this: point()[position()=10] . Here's an example; say that I wanted to position a point just before the e in the text in Mercury's < NAME > element:

 <?xml version="1.0"?>  <?xml-stylesheet type="text/xml" href="planets.xsl"?> <PLANETS>     <PLANET>  <NAME>Mercury</NAME>  <MASS UNITS="(Earth = 1)">.0553</MASS>         <DAY UNITS="days">58.65</DAY>         <RADIUS UNITS="miles">1516</RADIUS>         <DENSITY UNITS="(Earth = 1)">.983</DENSITY>         <DISTANCE UNITS="million miles">43.4</DISTANCE><!--At perihelion-->     </PLANET>     .     .     . 

In this case, I could use an expression like this to refer to the point right before the character e :

 xpointer(/PLANETS/PLANET[1]/NAME/text()/point()[position() = 1]) 

Similarly, I can access the point right before the 6 in the text in Mercury's <DAY> element, 58.65 (which, of course is text, not a number), this way:

 xpointer(/PLANETS/PLANET[1]/DAY/text()/point()[position() = 3]) 

XPointer also supports these point- related functions:

• start-point( location-set ) Returns a location set with start points in it. Those points are the start points of ranges that would cover the passed locations. For example, start-point(//PLANET[2]) would return the point immediately before the second <PLANET> element in the document, and start-point(//PLANET) would return a location set of the points just before each <PLANET> element.

• end-point( location-set ) Is the same as start-point , except that it returns the corresponding end points of the ranges that cover the locations passed to it.