libxml2
Loading...
Searching...
No Matches
xpath.h File Reference

XML Path Language implementation. More...

Data Structures

struct  _xmlNodeSet
 A node-set (an unordered collection of nodes without duplicates). More...
struct  _xmlXPathObject
 An XPath object. More...
struct  _xmlXPathContext
 Expression evaluation occurs with respect to a context. More...
struct  _xmlXPathParserContext
 An XPath parser context. More...

Macros

#define XML_XPATH_CHECKNS   (1<<0)
 Flags for XPath engine compilation and runtime.
#define XML_XPATH_NOVAR   (1<<1)
 forbid variables in expression

Typedefs

typedef struct _xmlXPathContext xmlXPathContext
 XPath context.
typedef struct _xmlXPathParserContext xmlXPathParserContext
 XPath parser and evaluation context.
typedef struct _xmlNodeSet xmlNodeSet
 XPath node set.
typedef struct _xmlXPathObject xmlXPathObject
 XPath object.
typedef void(* xmlXPathFunction) (xmlXPathParserContext *ctxt, int nargs)
 An XPath function.
typedef xmlXPathObject *(* xmlXPathVariableLookupFunc) (void *ctxt, const xmlChar *name, const xmlChar *ns_uri)
 Prototype for callbacks used to plug variable lookup in the XPath engine.
typedef xmlXPathFunction(* xmlXPathFuncLookupFunc) (void *ctxt, const xmlChar *name, const xmlChar *ns_uri)
 Prototype for callbacks used to plug function lookup in the XPath engine.
typedef struct _xmlXPathCompExpr xmlXPathCompExpr
 Compiled XPath expression.

Enumerations

enum  xmlXPathError
 The set of XPath error codes.
enum  xmlXPathObjectType
 An expression is evaluated to yield an object, which has one of the following four basic types: More...

Functions

void xmlXPathFreeObject (xmlXPathObject *obj)
 Objects and Nodesets handling.
xmlNodeSetxmlXPathNodeSetCreate (xmlNode *val)
 Create a new xmlNodeSet of type double and of value val
void xmlXPathFreeNodeSetList (xmlXPathObject *obj)
 Free up the xmlXPathObject obj but don't deallocate the objects in the list contrary to xmlXPathFreeObject.
void xmlXPathFreeNodeSet (xmlNodeSet *obj)
 Free the NodeSet compound (not the actual nodes !).
xmlXPathObjectxmlXPathObjectCopy (xmlXPathObject *val)
 allocate a new copy of a given object
int xmlXPathCmpNodes (xmlNode *node1, xmlNode *node2)
 Compare two nodes w.r.t document order.
int xmlXPathCastNumberToBoolean (double val)
 Conversion functions to basic types.
int xmlXPathCastStringToBoolean (const xmlChar *val)
 Converts a string to its boolean value.
int xmlXPathCastNodeSetToBoolean (xmlNodeSet *ns)
 Converts a node-set to its boolean value.
int xmlXPathCastToBoolean (xmlXPathObject *val)
 Converts an XPath object to its boolean value.
double xmlXPathCastBooleanToNumber (int val)
 Converts a boolean to its number value.
double xmlXPathCastStringToNumber (const xmlChar *val)
 Converts a string to its number value.
double xmlXPathCastNodeToNumber (xmlNode *node)
 Converts a node to its number value.
double xmlXPathCastNodeSetToNumber (xmlNodeSet *ns)
 Converts a node-set to its number value.
double xmlXPathCastToNumber (xmlXPathObject *val)
 Converts an XPath object to its number value.
xmlCharxmlXPathCastBooleanToString (int val)
 Converts a boolean to its string value.
xmlCharxmlXPathCastNumberToString (double val)
 Converts a number to its string value.
xmlCharxmlXPathCastNodeToString (xmlNode *node)
 Converts a node to its string value.
xmlCharxmlXPathCastNodeSetToString (xmlNodeSet *ns)
 Converts a node-set to its string value.
xmlCharxmlXPathCastToString (xmlXPathObject *val)
 Converts an existing object to its string() equivalent.
xmlXPathObjectxmlXPathConvertBoolean (xmlXPathObject *val)
 Converts an existing object to its boolean() equivalent.
xmlXPathObjectxmlXPathConvertNumber (xmlXPathObject *val)
 Converts an existing object to its number() equivalent.
xmlXPathObjectxmlXPathConvertString (xmlXPathObject *val)
 Converts an existing object to its string() equivalent.
xmlXPathContextxmlXPathNewContext (xmlDoc *doc)
 Context handling.
void xmlXPathFreeContext (xmlXPathContext *ctxt)
 Free up an xmlXPathContext.
void xmlXPathSetErrorHandler (xmlXPathContext *ctxt, xmlStructuredErrorFunc handler, void *context)
 Register a callback function that will be called on errors and warnings.
int xmlXPathContextSetCache (xmlXPathContext *ctxt, int active, int value, int options)
 Creates/frees an object cache on the XPath context.
long xmlXPathOrderDocElems (xmlDoc *doc)
 Evaluation functions.
int xmlXPathSetContextNode (xmlNode *node, xmlXPathContext *ctx)
 Sets 'node' as the context node.
xmlXPathObjectxmlXPathNodeEval (xmlNode *node, const xmlChar *str, xmlXPathContext *ctx)
 Evaluate the XPath Location Path in the given context.
xmlXPathObjectxmlXPathEval (const xmlChar *str, xmlXPathContext *ctx)
 Evaluate the XPath Location Path in the given context.
xmlXPathObjectxmlXPathEvalExpression (const xmlChar *str, xmlXPathContext *ctxt)
 Alias for xmlXPathEval.
int xmlXPathEvalPredicate (xmlXPathContext *ctxt, xmlXPathObject *res)
 Evaluate a predicate result for the current node.
xmlXPathCompExprxmlXPathCompile (const xmlChar *str)
 Separate compilation/evaluation entry points.
xmlXPathCompExprxmlXPathCtxtCompile (xmlXPathContext *ctxt, const xmlChar *str)
 Compile an XPath expression.
xmlXPathObjectxmlXPathCompiledEval (xmlXPathCompExpr *comp, xmlXPathContext *ctx)
 Evaluate the Precompiled XPath expression in the given context.
int xmlXPathCompiledEvalToBoolean (xmlXPathCompExpr *comp, xmlXPathContext *ctxt)
 Applies the XPath boolean() function on the result of the given compiled expression.
void xmlXPathFreeCompExpr (xmlXPathCompExpr *comp)
 Free up the memory allocated by comp
void xmlXPathInit (void)
int xmlXPathIsNaN (double val)
 Checks whether a double is a NaN.
int xmlXPathIsInf (double val)
 Checks whether a double is an infinity.

Detailed Description

XML Path Language implementation.

API for the XML Path Language implementation

XML Path Language implementation XPath is a language for addressing parts of an XML document, designed to be used by both XSLT and XPointer http://www.w3.org/TR/xpath

Implements W3C Recommendation 16 November 1999 http://www.w3.org/TR/1999/REC-xpath-19991116

Author
Daniel Veillard

Macro Definition Documentation

◆ XML_XPATH_CHECKNS

#define XML_XPATH_CHECKNS   (1<<0)

Flags for XPath engine compilation and runtime.

check namespaces at compilation

Typedef Documentation

◆ xmlXPathFuncLookupFunc

typedef xmlXPathFunction(* xmlXPathFuncLookupFunc) (void *ctxt, const xmlChar *name, const xmlChar *ns_uri)

Prototype for callbacks used to plug function lookup in the XPath engine.

Parameters
ctxtan XPath context
namename of the function
ns_urithe namespace name hosting this function
Returns
the XPath function or NULL if not found.

◆ xmlXPathFunction

typedef void(* xmlXPathFunction) (xmlXPathParserContext *ctxt, int nargs)

An XPath function.

The arguments (if any) are popped out from the context stack and the result is pushed on the stack.

Parameters
ctxtthe XPath interprestation context
nargsthe number of arguments

◆ xmlXPathVariableLookupFunc

typedef xmlXPathObject *(* xmlXPathVariableLookupFunc) (void *ctxt, const xmlChar *name, const xmlChar *ns_uri)

Prototype for callbacks used to plug variable lookup in the XPath engine.

Parameters
ctxtan XPath context
namename of the variable
ns_urithe namespace name hosting this variable
Returns
the XPath object value or NULL if not found.

Enumeration Type Documentation

◆ xmlXPathObjectType

An expression is evaluated to yield an object, which has one of the following four basic types:

  • node-set
  • boolean
  • number
  • string

Function Documentation

◆ xmlXPathCastBooleanToNumber()

double xmlXPathCastBooleanToNumber ( int val)

Converts a boolean to its number value.

Parameters
vala boolean
Returns
the number value

◆ xmlXPathCastBooleanToString()

xmlChar * xmlXPathCastBooleanToString ( int val)

Converts a boolean to its string value.

Parameters
vala boolean
Returns
a newly allocated string.

◆ xmlXPathCastNodeSetToBoolean()

int xmlXPathCastNodeSetToBoolean ( xmlNodeSet * ns)

Converts a node-set to its boolean value.

Parameters
nsa node-set
Returns
the boolean value

◆ xmlXPathCastNodeSetToNumber()

double xmlXPathCastNodeSetToNumber ( xmlNodeSet * ns)

Converts a node-set to its number value.

Parameters
nsa node-set
Returns
the number value

◆ xmlXPathCastNodeSetToString()

xmlChar * xmlXPathCastNodeSetToString ( xmlNodeSet * ns)

Converts a node-set to its string value.

Parameters
nsa node-set
Returns
a newly allocated string.

◆ xmlXPathCastNodeToNumber()

double xmlXPathCastNodeToNumber ( xmlNode * node)

Converts a node to its number value.

Parameters
nodea node
Returns
the number value

◆ xmlXPathCastNodeToString()

xmlChar * xmlXPathCastNodeToString ( xmlNode * node)

Converts a node to its string value.

Parameters
nodea node
Returns
a newly allocated string.

◆ xmlXPathCastNumberToBoolean()

int xmlXPathCastNumberToBoolean ( double val)

Conversion functions to basic types.

Conversion functions to basic types.

Parameters
vala number
Returns
the boolean value

◆ xmlXPathCastNumberToString()

xmlChar * xmlXPathCastNumberToString ( double val)

Converts a number to its string value.

Parameters
vala number
Returns
a newly allocated string.

◆ xmlXPathCastStringToBoolean()

int xmlXPathCastStringToBoolean ( const xmlChar * val)

Converts a string to its boolean value.

Parameters
vala string
Returns
the boolean value

◆ xmlXPathCastStringToNumber()

double xmlXPathCastStringToNumber ( const xmlChar * val)

Converts a string to its number value.

Parameters
vala string
Returns
the number value

◆ xmlXPathCastToBoolean()

int xmlXPathCastToBoolean ( xmlXPathObject * val)

Converts an XPath object to its boolean value.

Parameters
valan XPath object
Returns
the boolean value

◆ xmlXPathCastToNumber()

double xmlXPathCastToNumber ( xmlXPathObject * val)

Converts an XPath object to its number value.

Parameters
valan XPath object
Returns
the number value

◆ xmlXPathCastToString()

xmlChar * xmlXPathCastToString ( xmlXPathObject * val)

Converts an existing object to its string() equivalent.

Parameters
valan XPath object
Returns
the allocated string value of the object, NULL in case of error. It's up to the caller to free the string memory with xmlFree.

◆ xmlXPathCmpNodes()

int xmlXPathCmpNodes ( xmlNode * node1,
xmlNode * node2 )

Compare two nodes w.r.t document order.

Parameters
node1the first node
node2the second node
Returns
-2 in case of error 1 if first point < second point, 0 if it's the same node, -1 otherwise

◆ xmlXPathCompile()

xmlXPathCompExpr * xmlXPathCompile ( const xmlChar * str)

Separate compilation/evaluation entry points.

Separate compilation/evaluation entry points.

Parameters
strthe XPath expression
Returns
the xmlXPathCompExpr resulting from the compilation or NULL. the caller has to free the object.

◆ xmlXPathCompiledEval()

xmlXPathObject * xmlXPathCompiledEval ( xmlXPathCompExpr * comp,
xmlXPathContext * ctx )

Evaluate the Precompiled XPath expression in the given context.

Parameters
compthe compiled XPath expression
ctxthe XPath context
Returns
the xmlXPathObject resulting from the evaluation or NULL. the caller has to free the object.

◆ xmlXPathCompiledEvalToBoolean()

int xmlXPathCompiledEvalToBoolean ( xmlXPathCompExpr * comp,
xmlXPathContext * ctxt )

Applies the XPath boolean() function on the result of the given compiled expression.

Parameters
compthe compiled XPath expression
ctxtthe XPath context
Returns
1 if the expression evaluated to true, 0 if to false and -1 in API and internal errors.

◆ xmlXPathContextSetCache()

int xmlXPathContextSetCache ( xmlXPathContext * ctxt,
int active,
int value,
int options )

Creates/frees an object cache on the XPath context.

If activates XPath objects (xmlXPathObject) will be cached internally to be reused.

options must be set to 0 to enable XPath object caching. Other values for options have currently no effect.

value sets the maximum number of XPath objects to be cached per slot. There are two slots for node-set and misc objects. Use <0 for the default number (100).

Parameters
ctxtthe XPath context
activeenables/disables (creates/frees) the cache
valuea value with semantics dependent on options
optionsoptions (currently only the value 0 is used)
Returns
0 if the setting succeeded, and -1 on API or internal errors.

◆ xmlXPathConvertBoolean()

xmlXPathObject * xmlXPathConvertBoolean ( xmlXPathObject * val)

Converts an existing object to its boolean() equivalent.

Parameters
valan XPath object
Returns
the new object, the old one is freed (or the operation is done directly on val)

◆ xmlXPathConvertNumber()

xmlXPathObject * xmlXPathConvertNumber ( xmlXPathObject * val)

Converts an existing object to its number() equivalent.

Parameters
valan XPath object
Returns
the new object, the old one is freed (or the operation is done directly on val)

◆ xmlXPathConvertString()

xmlXPathObject * xmlXPathConvertString ( xmlXPathObject * val)

Converts an existing object to its string() equivalent.

Parameters
valan XPath object
Returns
the new object, the old one is freed (or the operation is done directly on val)

◆ xmlXPathCtxtCompile()

xmlXPathCompExpr * xmlXPathCtxtCompile ( xmlXPathContext * ctxt,
const xmlChar * str )

Compile an XPath expression.

Parameters
ctxtan XPath context
strthe XPath expression
Returns
the xmlXPathCompExpr resulting from the compilation or NULL. the caller has to free the object.

◆ xmlXPathEval()

xmlXPathObject * xmlXPathEval ( const xmlChar * str,
xmlXPathContext * ctx )

Evaluate the XPath Location Path in the given context.

Parameters
strthe XPath expression
ctxthe XPath context
Returns
the xmlXPathObject resulting from the evaluation or NULL. the caller has to free the object.

◆ xmlXPathEvalExpression()

xmlXPathObject * xmlXPathEvalExpression ( const xmlChar * str,
xmlXPathContext * ctxt )

Alias for xmlXPathEval.

Parameters
strthe XPath expression
ctxtthe XPath context
Returns
the xmlXPathObject resulting from the evaluation or NULL. the caller has to free the object.

◆ xmlXPathEvalPredicate()

int xmlXPathEvalPredicate ( xmlXPathContext * ctxt,
xmlXPathObject * res )

Evaluate a predicate result for the current node.

A PredicateExpr is evaluated by evaluating the Expr and converting the result to a boolean. If the result is a number, the result will be converted to true if the number is equal to the position of the context node in the context node list (as returned by the position function) and will be converted to false otherwise; if the result is not a number, then the result will be converted as if by a call to the boolean function.

Parameters
ctxtthe XPath context
resthe Predicate Expression evaluation result
Returns
1 if predicate is true, 0 otherwise

◆ xmlXPathFreeCompExpr()

void xmlXPathFreeCompExpr ( xmlXPathCompExpr * comp)

Free up the memory allocated by comp

Parameters
compan XPATH comp

◆ xmlXPathFreeContext()

void xmlXPathFreeContext ( xmlXPathContext * ctxt)

Free up an xmlXPathContext.

Parameters
ctxtthe context to free

◆ xmlXPathFreeNodeSet()

void xmlXPathFreeNodeSet ( xmlNodeSet * obj)

Free the NodeSet compound (not the actual nodes !).

Parameters
objthe xmlNodeSet to free

◆ xmlXPathFreeNodeSetList()

void xmlXPathFreeNodeSetList ( xmlXPathObject * obj)

Free up the xmlXPathObject obj but don't deallocate the objects in the list contrary to xmlXPathFreeObject.

Parameters
objan existing NodeSetList object

◆ xmlXPathFreeObject()

void xmlXPathFreeObject ( xmlXPathObject * obj)

Objects and Nodesets handling.

Objects and Nodesets handling.

Parameters
objthe object to free

◆ xmlXPathInit()

void xmlXPathInit ( void )

◆ xmlXPathIsInf()

int xmlXPathIsInf ( double val)

Checks whether a double is an infinity.

Parameters
vala double value
Returns
1 if the value is +Infinite, -1 if -Infinite, 0 otherwise

◆ xmlXPathIsNaN()

int xmlXPathIsNaN ( double val)

Checks whether a double is a NaN.

Parameters
vala double value
Returns
1 if the value is a NaN, 0 otherwise

◆ xmlXPathNewContext()

xmlXPathContext * xmlXPathNewContext ( xmlDoc * doc)

Context handling.

Context handling.

Parameters
docthe XML document
Returns
the xmlXPathContext just allocated. The caller will need to free it.

◆ xmlXPathNodeEval()

xmlXPathObject * xmlXPathNodeEval ( xmlNode * node,
const xmlChar * str,
xmlXPathContext * ctx )

Evaluate the XPath Location Path in the given context.

The node 'node' is set as the context node. The context node is not restored.

Parameters
nodethe node to to use as the context node
strthe XPath expression
ctxthe XPath context
Returns
the xmlXPathObject resulting from the evaluation or NULL. the caller has to free the object.

◆ xmlXPathNodeSetCreate()

xmlNodeSet * xmlXPathNodeSetCreate ( xmlNode * val)

Create a new xmlNodeSet of type double and of value val

Parameters
valan initial xmlNode, or NULL
Returns
the newly created object.

◆ xmlXPathObjectCopy()

xmlXPathObject * xmlXPathObjectCopy ( xmlXPathObject * val)

allocate a new copy of a given object

Parameters
valthe original object
Returns
the newly created object.

◆ xmlXPathOrderDocElems()

long xmlXPathOrderDocElems ( xmlDoc * doc)

Evaluation functions.

Evaluation functions.

This stamps all the element nodes with the document order Like for line information, the order is kept in the element->content field, the value stored is actually - the node number (starting at -1) to be able to differentiate from line numbers.

Parameters
docan input document
Returns
the number of elements found in the document or -1 in case of error.

◆ xmlXPathSetContextNode()

int xmlXPathSetContextNode ( xmlNode * node,
xmlXPathContext * ctx )

Sets 'node' as the context node.

The node must be in the same document as that associated with the context.

Parameters
nodethe node to to use as the context node
ctxthe XPath context
Returns
-1 in case of error or 0 if successful

◆ xmlXPathSetErrorHandler()

void xmlXPathSetErrorHandler ( xmlXPathContext * ctxt,
xmlStructuredErrorFunc handler,
void * data )

Register a callback function that will be called on errors and warnings.

If handler is NULL, the error handler will be deactivated.

Since
2.13.0
Parameters
ctxtthe XPath context
handlererror handler
datauser data which will be passed to the handler