xpointer: API to handle XML Pointers

## xpointer

xpointer - API to handle XML Pointers

API to handle XML Pointers Base implementation was made accordingly to W3C Candidate Recommendation 7 June 2000

Author(s): Daniel Veillard

## Synopsis

    typedef struct _xmlLocationSet xmlLocationSet;
    typedef xmlLocationSet * xmlLocationSetPtr;
    xmlXPathObjectPtr	xmlXPtrNewRange	(xmlNodePtr start,
    					 int startindex,
    					 xmlNodePtr end,
    					 int endindex);
    void	xmlXPtrFreeLocationSet		(xmlLocationSetPtr obj);
    xmlXPathObjectPtr	xmlXPtrWrapLocationSet	(xmlLocationSetPtr val);
    xmlNodePtr	xmlXPtrBuildNodeList	(xmlXPathObjectPtr obj);
    xmlXPathObjectPtr	xmlXPtrEval	(const xmlChar * str,
    					 xmlXPathContextPtr ctx);
    xmlXPathObjectPtr	xmlXPtrNewRangeNodes	(xmlNodePtr start,
    						 xmlNodePtr end);
    void	xmlXPtrLocationSetAdd		(xmlLocationSetPtr cur,
    					 xmlXPathObjectPtr val);
    void	xmlXPtrRangeToFunction		(xmlXPathParserContextPtr ctxt,
    					 int nargs);
    xmlXPathObjectPtr	xmlXPtrNewCollapsedRange	(xmlNodePtr start);
    xmlXPathObjectPtr	xmlXPtrNewRangePoints	(xmlXPathObjectPtr start,
    						 xmlXPathObjectPtr end);
    xmlXPathObjectPtr	xmlXPtrNewLocationSetNodeSet	(xmlNodeSetPtr set);
    xmlXPathObjectPtr	xmlXPtrNewRangePointNode	(xmlXPathObjectPtr start,
    							 xmlNodePtr end);
    xmlLocationSetPtr	xmlXPtrLocationSetCreate	(xmlXPathObjectPtr val);
    xmlXPathObjectPtr	xmlXPtrNewRangeNodeObject	(xmlNodePtr start,
    							 xmlXPathObjectPtr end);
    xmlXPathContextPtr	xmlXPtrNewContext	(xmlDocPtr doc,
    						 xmlNodePtr here,
    						 xmlNodePtr origin);
    void	xmlXPtrLocationSetRemove	(xmlLocationSetPtr cur,
    					 int val);
    xmlXPathObjectPtr	xmlXPtrNewRangeNodePoint	(xmlNodePtr start,
    							 xmlXPathObjectPtr end);
    void	xmlXPtrLocationSetDel		(xmlLocationSetPtr cur,
    					 xmlXPathObjectPtr val);
    xmlLocationSetPtr	xmlXPtrLocationSetMerge	(xmlLocationSetPtr val1,
    						 xmlLocationSetPtr val2);
    void	xmlXPtrEvalRangePredicate	(xmlXPathParserContextPtr ctxt);
    xmlXPathObjectPtr	xmlXPtrNewLocationSetNodes	(xmlNodePtr start,
    							 xmlNodePtr end);

## Description

## Details

### Structure xmlLocationSet

    struct _xmlLocationSet {
        int	locNr	: number of locations in the set
        int	locMax	: size of the array as allocated
        xmlXPathObjectPtr *	locTab	: array of locations
    } xmlLocationSet;

### Typedef xmlLocationSetPtr

    xmlLocationSet * xmlLocationSetPtr;

### xmlXPtrBuildNodeList ()

    xmlNodePtr	xmlXPtrBuildNodeList	(xmlXPathObjectPtr obj)

Build a node list tree copy of the XPointer result. This will drop Attributes and Namespace declarations.

`obj`: | the XPointer result from the evaluation.
`Returns`: | an xmlNodePtr list or NULL. the caller has to free the node tree.

### xmlXPtrEval ()

    xmlXPathObjectPtr	xmlXPtrEval	(const xmlChar * str,
    					 xmlXPathContextPtr ctx)

Evaluate the XPath Location Path in the given context.

`str`: | the XPointer expression
`ctx`: | the XPointer context
`Returns`: | the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

### xmlXPtrEvalRangePredicate ()

    void	xmlXPtrEvalRangePredicate	(xmlXPathParserContextPtr ctxt)

[8] Predicate ::= '[' PredicateExpr ']' [9] PredicateExpr ::= Expr Evaluate a predicate as in xmlXPathEvalPredicate() but for a Location Set instead of a node set

`ctxt`: | the XPointer Parser context

### xmlXPtrFreeLocationSet ()

    void	xmlXPtrFreeLocationSet		(xmlLocationSetPtr obj)

Free the LocationSet compound (not the actual ranges !).

`obj`: | the xmlLocationSetPtr to free

### xmlXPtrLocationSetAdd ()

    void	xmlXPtrLocationSetAdd		(xmlLocationSetPtr cur,
    					 xmlXPathObjectPtr val)

add a new xmlXPathObjectPtr to an existing LocationSet If the location already exist in the set @val is freed.

`cur`: | the initial range set
`val`: | a new xmlXPathObjectPtr

### xmlXPtrLocationSetCreate ()

    xmlLocationSetPtr	xmlXPtrLocationSetCreate	(xmlXPathObjectPtr val)

Create a new xmlLocationSetPtr of type double and of value @val

`val`: | an initial xmlXPathObjectPtr, or NULL
`Returns`: | the newly created object.

### xmlXPtrLocationSetDel ()

    void	xmlXPtrLocationSetDel		(xmlLocationSetPtr cur,
    					 xmlXPathObjectPtr val)

Removes an xmlXPathObjectPtr from an existing LocationSet

`cur`: | the initial range set
`val`: | an xmlXPathObjectPtr

### xmlXPtrLocationSetMerge ()

    xmlLocationSetPtr	xmlXPtrLocationSetMerge	(xmlLocationSetPtr val1,
    						 xmlLocationSetPtr val2)

Merges two rangesets, all ranges from @val2 are added to @val1

`val1`: | the first LocationSet
`val2`: | the second LocationSet
`Returns`: | val1 once extended or NULL in case of error.

### xmlXPtrLocationSetRemove ()

    void	xmlXPtrLocationSetRemove	(xmlLocationSetPtr cur,
    					 int val)

Removes an entry from an existing LocationSet list.

`cur`: | the initial range set
`val`: | the index to remove

### xmlXPtrNewCollapsedRange ()

    xmlXPathObjectPtr	xmlXPtrNewCollapsedRange	(xmlNodePtr start)

Create a new xmlXPathObjectPtr of type range using a single nodes

`start`: | the starting and ending node
`Returns`: | the newly created object.

### xmlXPtrNewContext ()

    xmlXPathContextPtr	xmlXPtrNewContext	(xmlDocPtr doc,
    						 xmlNodePtr here,
    						 xmlNodePtr origin)

Create a new XPointer context

`doc`: | the XML document
`here`: | the node that directly contains the XPointer being evaluated or NULL
`origin`: | the element from which a user or program initiated traversal of the link, or NULL.
`Returns`: | the xmlXPathContext just allocated.

### xmlXPtrNewLocationSetNodeSet ()

    xmlXPathObjectPtr	xmlXPtrNewLocationSetNodeSet	(xmlNodeSetPtr set)

Create a new xmlXPathObjectPtr of type LocationSet and initialize it with all the nodes from @set

`set`: | a node set
`Returns`: | the newly created object.

### xmlXPtrNewLocationSetNodes ()

    xmlXPathObjectPtr	xmlXPtrNewLocationSetNodes	(xmlNodePtr start,
    							 xmlNodePtr end)

Create a new xmlXPathObjectPtr of type LocationSet and initialize it with the single range made of the two nodes @start and @end

`start`: | the start NodePtr value
`end`: | the end NodePtr value or NULL
`Returns`: | the newly created object.

### xmlXPtrNewRange ()

    xmlXPathObjectPtr	xmlXPtrNewRange	(xmlNodePtr start,
    					 int startindex,
    					 xmlNodePtr end,
    					 int endindex)

Create a new xmlXPathObjectPtr of type range

`start`: | the starting node
`startindex`: | the start index
`end`: | the ending point
`endindex`: | the ending index
`Returns`: | the newly created object.

### xmlXPtrNewRangeNodeObject ()

    xmlXPathObjectPtr	xmlXPtrNewRangeNodeObject	(xmlNodePtr start,
    							 xmlXPathObjectPtr end)

Create a new xmlXPathObjectPtr of type range from a not to an object

`start`: | the starting node
`end`: | the ending object
`Returns`: | the newly created object.

### xmlXPtrNewRangeNodePoint ()

    xmlXPathObjectPtr	xmlXPtrNewRangeNodePoint	(xmlNodePtr start,
    							 xmlXPathObjectPtr end)

Create a new xmlXPathObjectPtr of type range from a node to a point

`start`: | the starting node
`end`: | the ending point
`Returns`: | the newly created object.

### xmlXPtrNewRangeNodes ()

    xmlXPathObjectPtr	xmlXPtrNewRangeNodes	(xmlNodePtr start,
    						 xmlNodePtr end)

Create a new xmlXPathObjectPtr of type range using 2 nodes

`start`: | the starting node
`end`: | the ending node
`Returns`: | the newly created object.

### xmlXPtrNewRangePointNode ()

    xmlXPathObjectPtr	xmlXPtrNewRangePointNode	(xmlXPathObjectPtr start,
    							 xmlNodePtr end)

Create a new xmlXPathObjectPtr of type range from a point to a node

`start`: | the starting point
`end`: | the ending node
`Returns`: | the newly created object.

### xmlXPtrNewRangePoints ()

    xmlXPathObjectPtr	xmlXPtrNewRangePoints	(xmlXPathObjectPtr start,
    						 xmlXPathObjectPtr end)

Create a new xmlXPathObjectPtr of type range using 2 Points

`start`: | the starting point
`end`: | the ending point
`Returns`: | the newly created object.

### xmlXPtrRangeToFunction ()

    void	xmlXPtrRangeToFunction		(xmlXPathParserContextPtr ctxt,
    					 int nargs)

Implement the range-to() XPointer function Obsolete. range-to is not a real function but a special type of location step which is handled in xpath.c.

`ctxt`: | the XPointer Parser context
`nargs`: | the number of args

### xmlXPtrWrapLocationSet ()

    xmlXPathObjectPtr	xmlXPtrWrapLocationSet	(xmlLocationSetPtr val)

Wrap the LocationSet @val in a new xmlXPathObjectPtr

`val`: | the LocationSet value
`Returns`: | the newly created object.