Package XPointer for XML C APIs

14 Package XPointer for XML C APIs

Package XPointer methods implement XML pointers for XML C APIs. They are grouped into three interface types:

14.1 XPointer Interface for XPointer XML C APIs

The following table summarizes the methods available through the XPointer interface of XPointer for XML C APIs.

Table 14-1 Summary of XPointer XPointer Methods for XML C Implementation

Function	Summary
XmlXPointerEval()	Evaluates XPointer string.

14.1.1 XmlXPointerEval()

Parses and evaluates xpointer string and calculates locations in the document.

Syntax

xmlxptrlocset* XmlXPointerEval(
   xmldocnode* doc,
   oratext* xptrstr);

Parameter	In/Out	Description
doc	IN	document node of the corresponding DOM tree
xptrstr	IN	xpointer string

Returns

(xmlxptrlocset *) calculated location set

14.2 XPtrLoc Interface for XPointer XML C APIs

The following table summarizes the methods available through the XPtrLoc interface of XPointer for XML C API.

Table 14-2 Summary of XPtrLoc XPointer Methods for XML C Implementation

Function	Summary
XmlXPtrLocGetNode()	Returns Xml node from `XPtrLoc`.
XmlXPtrLocGetPoint()	Returns Xml point from `XPtrLoc`.
XmlXPtrLocGetRange()	Returns Xml range from `XPtrLoc`.
XmlXPtrLocGetType()	Returns type of `XPtrLoc`.
XmlXPtrLocToString()	Returns string for a location.

14.2.1 XmlXPtrLocGetNode()

Returns node from location

Syntax

xmlnode* XmlXPtrLocGetNode(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	location

Returns

(xmlnode *) Node from location

14.2.2 XmlXPtrLocGetPoint()

Returns point from location

Syntax

xmlpoint* XmlXPtrLocGetPoint(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	location

Returns

(xmlpoint *) Point from location

14.2.3 XmlXPtrLocGetRange()

Returns range from location.

Syntax

xmlrange* XmlXPtrLocGetRange(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	location

Returns

(xmlrange *) Range from location

14.2.4 XmlXPtrLocGetType()

Returns type of location

Syntax

xmlxptrloctype XmlXPtrLocGetType(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	location

Returns

(xmlxptrloctype) Type of location

14.2.5 XmlXPtrLocToString()

Returns string for a location:

- node name: name of the container node

- names of container nodes: "not a location" otherwise

Syntax

oratext* XmlXPtrLocToString(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	location

Returns

(oratext *) string

14.3 XPtrLocSet Interface for XPointer XML C APIs

The following table summarizes the methods available through the XPtrLocSet interface of XPointer for XML C APIs.

Table 14-3 Summary of XPtrLocSet XPointer Methods for XML C Implementation

Function	Summary
XmlXPtrLocSetFree()	Free a location set
XmlXPtrLocSetGetItem()	Returns location with `idx` position in `XPtrLocSet`
XmlXPtrLocSetGetLength()	Returns length of `XPtrLocSet`.

14.3.1 XmlXPtrLocSetFree()

It is user's responsibility to call this function on every location set returned by XPointer or XPtrLocSet interfaces

Syntax

void XmlXPtrLocSetFree(
   xmlxptrlocset* locset);

Parameter	In/Out	Description
locset	IN	location set

14.3.2 XmlXPtrLocSetGetItem()

Returns location with idx position in the location set. First position is 1.

Syntax

xmlxptrloc* XmlXPtrLocSetGetItem(
   xmlxptrlocset* locset, 
   ub4 idx);

Parameter	In/Out	Description
locset	IN	location set
idx	IN	location index

Returns

(xmlxptrloc *) location with the position idx

14.3.3 XmlXPtrLocSetGetLength()

Returns the number of locations in the location set

Syntax

ub4 XmlXPtrLocSetGetLength(
   xmlxptrlocset* locset);

Parameter	In/Out	Description
locset	IN	location set

Returns

(ub4) number of nodes in locset