Using XPointer Ranges

You can create ranges with two points, a start point and an end point, as long as they are in the same document and the start point is not after the end point. (If the start point and the end point are the same, the range is said to be collapsed . ) A range is all of the XML structure between those two points.

A range doesn't have to be a neat subsection of a document; it can extend from one subtree to another in the document, for example. All you need are a valid start point and a valid end point in the same document.

Range Functions

The XPointer specification adds a number of functions to those available in XPath to handle ranges:

• range( location-set ) This function takes the locations you pass to it and returns a range that completely covers the location. For example, an element location is converted to a range by returning the element's parent as the origin node, the start point as the number of previous siblings the element has, and the end point as one greater than the start point. In other words, this function is intended to cover locations with ranges.

• range-inside( location-set ) This function returns a range or ranges covering each location in the argument location set. For example, if you pass an element location, the result is a range that encloses all that is inside the element.

• range-to( location-set ) This function returns a range for each location in the location set. The start point of the range is the start point of the context location (as determined by the start-point function). 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.

String Ranges

The XPointer specification also includes a function for basic string matching, string-range() . This function returns a location set with one range for every nonoverlapping match to the search string. The match operation is case sensitive.

You can also specify optional index and length arguments to specify how many characters after the match the range should start and how many characters should be in the range. Here's how you use string-range() in general:

 string-range(  location_set,   string,  [  index,  [  length  ]]) 

Matching an Empty String

An empty string, "" , matches the location immediately before any character, so you can use an empty string to match to the very beginning of any string.

For example, this expression returns a location set containing ranges covering all matches to the word Saturn :

 string-range(/, "Saturn") 

To extract a specific match from the location set returned, you use the [] operator. For example, this expression returns a range covering the second occurrence of Saturn in the document:

 string-range(/, "Saturn")[2] 

This expression returns a range covering the third occurrence of the word Jupiter in the < NAME > element of the sixth <PLANET> element in a document:

 string-range(//PLANET[6]/NAME, "Jupiter")[3] 

You can also specify the range you want to return using the index (which starts with a value of 1 ) and length arguments. For example, this expression returns a range covering the letters er in the third occurrence of the word Jupiter in the <NAME> element of the sixth <PLANET> element:

 string-range(//PLANET[6]/NAME, "Jupiter", 6, 2)[3] 

If you want to locate a specific point, you can create a collapsed ( zero-length ) range like this:

 string-range(//PLANET[6]/NAME, "Jupiter", 6, 0)[3] 

Another way to get a specific point is to use the start-point() function, which returns the start point of a range:

 start-point(string-range(//PLANET[6]/NAME, "Jupiter", 6, 2)[3]) 

Here's an expression that locates the second @ character in any text node in the document and the five characters following it:

 string-range(/, "@", 1, 6)[2]