libxml2: xpath.h File Reference

libxml2

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
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.
xmlNodeSet * | xmlXPathNodeSetCreate (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 !).
xmlXPathObject * | xmlXPathObjectCopy (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.
xmlChar * | xmlXPathCastBooleanToString (int val)
| Converts a boolean to its string value.
xmlChar * | xmlXPathCastNumberToString (double val)
| Converts a number to its string value.
xmlChar * | xmlXPathCastNodeToString (xmlNode *node)
| Converts a node to its string value.
xmlChar * | xmlXPathCastNodeSetToString (xmlNodeSet *ns)
| Converts a node-set to its string value.
xmlChar * | xmlXPathCastToString (xmlXPathObject *val)
| Converts an existing object to its string() equivalent.
xmlXPathObject * | xmlXPathConvertBoolean (xmlXPathObject *val)
| Converts an existing object to its boolean() equivalent.
xmlXPathObject * | xmlXPathConvertNumber (xmlXPathObject *val)
| Converts an existing object to its number() equivalent.
xmlXPathObject * | xmlXPathConvertString (xmlXPathObject *val)
| Converts an existing object to its string() equivalent.
xmlXPathContext * | xmlXPathNewContext (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.
xmlXPathObject * | xmlXPathNodeEval (xmlNode *node, const xmlChar *str, xmlXPathContext *ctx)
| Evaluate the XPath Location Path in the given context.
xmlXPathObject * | xmlXPathEval (const xmlChar *str, xmlXPathContext *ctx)
| Evaluate the XPath Location Path in the given context.
xmlXPathObject * | xmlXPathEvalExpression (const xmlChar *str, xmlXPathContext *ctxt)
| Alias for xmlXPathEval.
int | xmlXPathEvalPredicate (xmlXPathContext *ctxt, xmlXPathObject *res)
| Evaluate a predicate result for the current node.
xmlXPathCompExpr * | xmlXPathCompile (const xmlChar *str)
| Separate compilation/evaluation entry points.
xmlXPathCompExpr * | xmlXPathCtxtCompile (xmlXPathContext *ctxt, const xmlChar *str)
| Compile an XPath expression.
xmlXPathObject * | xmlXPathCompiledEval (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

Copyright
  See Copyright for the status of this software.

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

  ctxt | an XPath context
  name | name of the function
  ns_uri | the 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

  ctxt | the XPath interprestation context
  nargs | the 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

  ctxt | an XPath context
  name | name of the variable
  ns_uri | the namespace name hosting this variable

Returns
  the XPath object value or NULL if not found.

## Enumeration Type Documentation

## ◆ xmlXPathObjectType

enum 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

  val | a boolean

Returns
  the number value

## ◆ xmlXPathCastBooleanToString()

xmlChar * xmlXPathCastBooleanToString | ( | int | val | ) |

Converts a boolean to its string value.

Parameters

  val | a boolean

Returns
  a newly allocated string.

## ◆ xmlXPathCastNodeSetToBoolean()

int xmlXPathCastNodeSetToBoolean | ( | xmlNodeSet * | ns | ) |

Converts a node-set to its boolean value.

Parameters

  ns | a node-set

Returns
  the boolean value

## ◆ xmlXPathCastNodeSetToNumber()

double xmlXPathCastNodeSetToNumber | ( | xmlNodeSet * | ns | ) |

Converts a node-set to its number value.

Parameters

  ns | a node-set

Returns
  the number value

## ◆ xmlXPathCastNodeSetToString()

xmlChar * xmlXPathCastNodeSetToString | ( | xmlNodeSet * | ns | ) |

Converts a node-set to its string value.

Parameters

  ns | a node-set

Returns
  a newly allocated string.

## ◆ xmlXPathCastNodeToNumber()

double xmlXPathCastNodeToNumber | ( | xmlNode * | node | ) |

Converts a node to its number value.

Parameters

  node | a node

Returns
  the number value

## ◆ xmlXPathCastNodeToString()

xmlChar * xmlXPathCastNodeToString | ( | xmlNode * | node | ) |

Converts a node to its string value.

Parameters

  node | a node

Returns
  a newly allocated string.

## ◆ xmlXPathCastNumberToBoolean()

int xmlXPathCastNumberToBoolean | ( | double | val | ) |

Conversion functions to basic types.

Converts a number to its boolean value.

Conversion functions to basic types.

Parameters

  val | a number

Returns
  the boolean value

## ◆ xmlXPathCastNumberToString()

xmlChar * xmlXPathCastNumberToString | ( | double | val | ) |

Converts a number to its string value.

Parameters

  val | a number

Returns
  a newly allocated string.

## ◆ xmlXPathCastStringToBoolean()

int xmlXPathCastStringToBoolean | ( | const xmlChar * | val | ) |

Converts a string to its boolean value.

Parameters

  val | a string

Returns
  the boolean value

## ◆ xmlXPathCastStringToNumber()

double xmlXPathCastStringToNumber | ( | const xmlChar * | val | ) |

Converts a string to its number value.

Parameters

  val | a string

Returns
  the number value

## ◆ xmlXPathCastToBoolean()

int xmlXPathCastToBoolean | ( | xmlXPathObject * | val | ) |

Converts an XPath object to its boolean value.

Parameters

  val | an XPath object

Returns
  the boolean value

## ◆ xmlXPathCastToNumber()

double xmlXPathCastToNumber | ( | xmlXPathObject * | val | ) |

Converts an XPath object to its number value.

Parameters

  val | an XPath object

Returns
  the number value

## ◆ xmlXPathCastToString()

xmlChar * xmlXPathCastToString | ( | xmlXPathObject * | val | ) |

Converts an existing object to its string() equivalent.

Parameters

  val | an 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

  node1 | the first node
  node2 | the 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.

Compile an XPath expression.

Separate compilation/evaluation entry points.

Parameters

  str | the 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

  comp | the compiled XPath expression
  ctx | the 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

  comp | the compiled XPath expression
  ctxt | the 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

  ctxt | the XPath context
  active | enables/disables (creates/frees) the cache
  value | a value with semantics dependent on options
  options | options (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

  val | an 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

  val | an 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

  val | an 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

  ctxt | an XPath context
  str | the 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

  str | the XPath expression
  ctx | the 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

  str | the XPath expression
  ctxt | the 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

  ctxt | the XPath context
  res | the 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

  comp | an XPATH comp

## ◆ xmlXPathFreeContext()

void xmlXPathFreeContext | ( | xmlXPathContext * | ctxt | ) |

Free up an xmlXPathContext.

Parameters

  ctxt | the context to free

## ◆ xmlXPathFreeNodeSet()

void xmlXPathFreeNodeSet | ( | xmlNodeSet * | obj | ) |

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

Parameters

  obj | the 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

  obj | an existing NodeSetList object

## ◆ xmlXPathFreeObject()

void xmlXPathFreeObject | ( | xmlXPathObject * | obj | ) |

Objects and Nodesets handling.

Free up an xmlXPathObject object.

Objects and Nodesets handling.

Parameters

  obj | the object to free

## ◆ xmlXPathInit()

void xmlXPathInit | ( | void |  | ) |

Deprecated
  Alias for xmlInitParser.

## ◆ xmlXPathIsInf()

int xmlXPathIsInf | ( | double | val | ) |

Checks whether a double is an infinity.

Parameters

  val | a 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

  val | a double value

Returns
  1 if the value is a NaN, 0 otherwise

## ◆ xmlXPathNewContext()

xmlXPathContext * xmlXPathNewContext | ( | xmlDoc * | doc | ) |

Context handling.

Create a new xmlXPathContext.

Context handling.

Parameters

  doc | the 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

  node | the node to to use as the context node
  str | the XPath expression
  ctx | the 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

  val | an initial xmlNode, or NULL

Returns
  the newly created object.

## ◆ xmlXPathObjectCopy()

xmlXPathObject * xmlXPathObjectCopy | ( | xmlXPathObject * | val | ) |

allocate a new copy of a given object

Parameters

  val | the original object

Returns
  the newly created object.

## ◆ xmlXPathOrderDocElems()

long xmlXPathOrderDocElems | ( | xmlDoc * | doc | ) |

Evaluation functions.

Call this routine to speed up XPath computation on static documents.

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

  doc | an 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

  node | the node to to use as the context node
  ctx | the 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

  ctxt | the XPath context
  handler | error handler
  data | user data which will be passed to the handler