Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

Module xpath from libxml2

API Menu
API Indexes
Related links

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

Table of Contents

#define XML_XPATH_CHECKNS
#define XML_XPATH_NOVAR
#define xmlXPathNodeSetGetLength
#define xmlXPathNodeSetIsEmpty
#define xmlXPathNodeSetItem
Structure xmlNodeSet
struct _xmlNodeSet
Typedef xmlNodeSet * xmlNodeSetPtr
Structure xmlXPathAxis
struct _xmlXPathAxis
Typedef xmlXPathAxis * xmlXPathAxisPtr
Structure xmlXPathCompExpr
struct _xmlXPathCompExpr The content of this structure is not made public by the API.
Typedef xmlXPathCompExpr * xmlXPathCompExprPtr
Structure xmlXPathContext
struct _xmlXPathContext
Typedef xmlXPathContext * xmlXPathContextPtr
Enum xmlXPathError
Typedef xmlXPathFunct * xmlXPathFuncPtr
Structure xmlXPathFunct
struct _xmlXPathFunct
Structure xmlXPathObject
struct _xmlXPathObject
Typedef xmlXPathObject * xmlXPathObjectPtr
Enum xmlXPathObjectType
Structure xmlXPathParserContext
struct _xmlXPathParserContext
Typedef xmlXPathParserContext * xmlXPathParserContextPtr
Structure xmlXPathType
struct _xmlXPathType
Typedef xmlXPathType * xmlXPathTypePtr
Structure xmlXPathVariable
struct _xmlXPathVariable
Typedef xmlXPathVariable * xmlXPathVariablePtr
Function type: xmlXPathAxisFunc
xmlXPathObjectPtr	xmlXPathAxisFunc	(xmlXPathParserContextPtr ctxt, 
xmlXPathObjectPtr cur)
double	xmlXPathCastBooleanToNumber	(int val)
xmlChar *	xmlXPathCastBooleanToString	(int val)
int	xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns)
double	xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns)
xmlChar *	xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns)
double	xmlXPathCastNodeToNumber	(xmlNodePtr node)
xmlChar *	xmlXPathCastNodeToString	(xmlNodePtr node)
int	xmlXPathCastNumberToBoolean	(double val)
xmlChar *	xmlXPathCastNumberToString	(double val)
int	xmlXPathCastStringToBoolean	(const xmlChar * val)
double	xmlXPathCastStringToNumber	(const xmlChar * val)
int	xmlXPathCastToBoolean		(xmlXPathObjectPtr val)
double	xmlXPathCastToNumber		(xmlXPathObjectPtr val)
xmlChar *	xmlXPathCastToString	(xmlXPathObjectPtr val)
int	xmlXPathCmpNodes		(xmlNodePtr node1, 
xmlNodePtr node2)
xmlXPathCompExprPtr	xmlXPathCompile	(const xmlChar * str)
xmlXPathObjectPtr	xmlXPathCompiledEval	(xmlXPathCompExprPtr comp, 
xmlXPathContextPtr ctx)
int	xmlXPathCompiledEvalToBoolean	(xmlXPathCompExprPtr comp, 
xmlXPathContextPtr ctxt)
int	xmlXPathContextSetCache		(xmlXPathContextPtr ctxt, 
int active,
int value,
int options)
xmlXPathObjectPtr	xmlXPathConvertBoolean	(xmlXPathObjectPtr val)
Function type: xmlXPathConvertFunc
int	xmlXPathConvertFunc		(xmlXPathObjectPtr obj, 
int type)
xmlXPathObjectPtr	xmlXPathConvertNumber	(xmlXPathObjectPtr val)
xmlXPathObjectPtr	xmlXPathConvertString	(xmlXPathObjectPtr val)
xmlXPathCompExprPtr	xmlXPathCtxtCompile	(xmlXPathContextPtr ctxt, 
const xmlChar * str)
xmlXPathObjectPtr	xmlXPathEval	(const xmlChar * str, 
xmlXPathContextPtr ctx)
xmlXPathObjectPtr	xmlXPathEvalExpression	(const xmlChar * str, 
xmlXPathContextPtr ctxt)
Function type: xmlXPathEvalFunc
void	xmlXPathEvalFunc		(xmlXPathParserContextPtr ctxt, 
int nargs)
int	xmlXPathEvalPredicate		(xmlXPathContextPtr ctxt, 
xmlXPathObjectPtr res)
void	xmlXPathFreeCompExpr		(xmlXPathCompExprPtr comp)
void	xmlXPathFreeContext		(xmlXPathContextPtr ctxt)
void	xmlXPathFreeNodeSet		(xmlNodeSetPtr obj)
void	xmlXPathFreeNodeSetList		(xmlXPathObjectPtr obj)
void	xmlXPathFreeObject		(xmlXPathObjectPtr obj)
Function type: xmlXPathFuncLookupFunc
xmlXPathFunction	xmlXPathFuncLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri)
Function type: xmlXPathFunction
void	xmlXPathFunction		(xmlXPathParserContextPtr ctxt, 
int nargs)
void	xmlXPathInit			(void)
int	xmlXPathIsInf			(double val)
int	xmlXPathIsNaN			(double val)
xmlXPathContextPtr	xmlXPathNewContext	(xmlDocPtr doc)
xmlNodeSetPtr	xmlXPathNodeSetCreate	(xmlNodePtr val)
xmlXPathObjectPtr	xmlXPathObjectCopy	(xmlXPathObjectPtr val)
long	xmlXPathOrderDocElems		(xmlDocPtr doc)
Function type: xmlXPathVariableLookupFunc
xmlXPathObjectPtr	xmlXPathVariableLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri)

Description

Macro: XML_XPATH_CHECKNS

#define XML_XPATH_CHECKNS

check namespaces at compilation

Macro: XML_XPATH_NOVAR

#define XML_XPATH_NOVAR

forbid variables in expression

Macro: xmlXPathNodeSetGetLength

#define xmlXPathNodeSetGetLength

Implement a functionality similar to the DOM NodeList.length. Returns the number of nodes in the node-set.

Macro: xmlXPathNodeSetIsEmpty

#define xmlXPathNodeSetIsEmpty

Checks whether @ns is empty or not. Returns %TRUE if @ns is an empty node-set.

Macro: xmlXPathNodeSetItem

#define xmlXPathNodeSetItem

Implements a functionality similar to the DOM NodeList.item(). Returns the xmlNodePtr at the given @index in @ns or NULL if @index is out of range (0 to length-1)

Structure xmlNodeSet

Structure xmlNodeSet
struct _xmlNodeSet { int nodeNr : number of nodes in the set int nodeMax : size of the array as allocated xmlNodePtr * nodeTab : array of nodes in no particular order @ }

Structure xmlXPathAxis

Structure xmlXPathAxis
struct _xmlXPathAxis { const xmlChar * name : the axis name xmlXPathAxisFunc func : the search function }

Structure xmlXPathCompExpr

Structure xmlXPathCompExpr
struct _xmlXPathCompExpr { The content of this structure is not made public by the API. }

Structure xmlXPathContext

Structure xmlXPathContext
struct _xmlXPathContext { xmlDocPtr doc : The current document xmlNodePtr node : The current node int nb_variables_unused : unused (hash table) int max_variables_unused : unused (hash table) xmlHashTablePtr varHash : Hash table of defined variables int nb_types : number of defined types int max_types : max number of types xmlXPathTypePtr types : Array of defined types int nb_funcs_unused : unused (hash table) int max_funcs_unused : unused (hash table) xmlHashTablePtr funcHash : Hash table of defined funcs int nb_axis : number of defined axis int max_axis : max number of axis xmlXPathAxisPtr axis : Array of defined axis the namespace nod xmlNsPtr * namespaces : Array of namespaces int nsNr : number of namespace in scope void * user : function to free extra variables int contextSize : the context size int proximityPosition : the proximity position extra stuff for int xptr : is this an XPointer context? xmlNodePtr here : for here() xmlNodePtr origin : for origin() the set of namespace decla xmlHashTablePtr nsHash : The namespaces hash table xmlXPathVariableLookupFunc varLookupFunc : variable lookup func void * varLookupData : variable lookup data Possibility to lin void * extra : needed for XSLT The function name and U const xmlChar * function const xmlChar * functionURI : function lookup function and data xmlXPathFuncLookupFunc funcLookupFunc : function lookup func void * funcLookupData : function lookup data temporary namespac xmlNsPtr * tmpNsList : Array of namespaces int tmpNsNr : number of namespaces in scope error rep void * userData : user specific data block xmlStructuredErrorFunc error : the callback in case of errors xmlError lastError : the last error xmlNodePtr debugNode : the source node XSLT dictionary xmlDictPtr dict : dictionary if any int flags : flags to control compilation Cache for void * cache }

Enum xmlXPathError

Enum xmlXPathError {
    XPATH_EXPRESSION_OK = 0
    XPATH_NUMBER_ERROR = 1
    XPATH_UNFINISHED_LITERAL_ERROR = 2
    XPATH_START_LITERAL_ERROR = 3
    XPATH_VARIABLE_REF_ERROR = 4
    XPATH_UNDEF_VARIABLE_ERROR = 5
    XPATH_INVALID_PREDICATE_ERROR = 6
    XPATH_EXPR_ERROR = 7
    XPATH_UNCLOSED_ERROR = 8
    XPATH_UNKNOWN_FUNC_ERROR = 9
    XPATH_INVALID_OPERAND = 10
    XPATH_INVALID_TYPE = 11
    XPATH_INVALID_ARITY = 12
    XPATH_INVALID_CTXT_SIZE = 13
    XPATH_INVALID_CTXT_POSITION = 14
    XPATH_MEMORY_ERROR = 15
    XPTR_SYNTAX_ERROR = 16
    XPTR_RESOURCE_ERROR = 17
    XPTR_SUB_RESOURCE_ERROR = 18
    XPATH_UNDEF_PREFIX_ERROR = 19
    XPATH_ENCODING_ERROR = 20
    XPATH_INVALID_CHAR_ERROR = 21
    XPATH_INVALID_CTXT = 22
}

Structure xmlXPathFunct

Structure xmlXPathFunct
struct _xmlXPathFunct { const xmlChar * name : the function name xmlXPathEvalFunc func : the evaluation function }

Structure xmlXPathObject

Structure xmlXPathObject
struct _xmlXPathObject { xmlXPathObjectType type xmlNodeSetPtr nodesetval int boolval double floatval xmlChar * stringval void * user int index void * user2 int index2 }

Enum xmlXPathObjectType

Enum xmlXPathObjectType {
    XPATH_UNDEFINED = 0
    XPATH_NODESET = 1
    XPATH_BOOLEAN = 2
    XPATH_NUMBER = 3
    XPATH_STRING = 4
    XPATH_POINT = 5
    XPATH_RANGE = 6
    XPATH_LOCATIONSET = 7
    XPATH_USERS = 8
    XPATH_XSLT_TREE = 9 : An XSLT value tree, non modifiable
}

Structure xmlXPathParserContext

Structure xmlXPathParserContext
struct _xmlXPathParserContext { const xmlChar * cur : the current char being parsed const xmlChar * base : the full expression int error : error code xmlXPathContextPtr context : the evaluation context xmlXPathObjectPtr value : the current value int valueNr : number of values stacked int valueMax : max number of values stacked xmlXPathObjectPtr * valueTab : stack of values xmlXPathCompExprPtr comp : the precompiled expression int xptr : it this an XPointer expression xmlNodePtr ancestor : used for walking preceding axis }

Structure xmlXPathType

Structure xmlXPathType
struct _xmlXPathType { const xmlChar * name : the type name xmlXPathConvertFunc func : the conversion function }

Structure xmlXPathVariable

Structure xmlXPathVariable
struct _xmlXPathVariable { const xmlChar * name : the variable name xmlXPathObjectPtr value : the value }

Function type: xmlXPathAxisFunc

Function type: xmlXPathAxisFunc
xmlXPathObjectPtr	xmlXPathAxisFunc	(xmlXPathParserContextPtr ctxt, 
xmlXPathObjectPtr cur)

An axis traversal function. To traverse an axis, the engine calls the first time with cur == NULL and repeat until the function returns NULL indicating the end of the axis traversal.

ctxt:the XPath interpreter context
cur:the previous node being explored on that axis
Returns:the next node in that axis or NULL if at the end of the axis.

Function: xmlXPathCastBooleanToNumber

double	xmlXPathCastBooleanToNumber	(int val)

Converts a boolean to its number value

val:a boolean
Returns:the number value

Function: xmlXPathCastBooleanToString

xmlChar *	xmlXPathCastBooleanToString	(int val)

Converts a boolean to its string value.

val:a boolean
Returns:a newly allocated string.

Function: xmlXPathCastNodeSetToBoolean

int	xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns)

Converts a node-set to its boolean value

ns:a node-set
Returns:the boolean value

Function: xmlXPathCastNodeSetToNumber

double	xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns)

Converts a node-set to its number value

ns:a node-set
Returns:the number value

Function: xmlXPathCastNodeSetToString

xmlChar *	xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns)

Converts a node-set to its string value.

ns:a node-set
Returns:a newly allocated string.

Function: xmlXPathCastNodeToNumber

double	xmlXPathCastNodeToNumber	(xmlNodePtr node)

Converts a node to its number value

node:a node
Returns:the number value

Function: xmlXPathCastNodeToString

xmlChar *	xmlXPathCastNodeToString	(xmlNodePtr node)

Converts a node to its string value.

node:a node
Returns:a newly allocated string.

Function: xmlXPathCastNumberToBoolean

int	xmlXPathCastNumberToBoolean	(double val)

Converts a number to its boolean value

val:a number
Returns:the boolean value

Function: xmlXPathCastNumberToString

xmlChar *	xmlXPathCastNumberToString	(double val)

Converts a number to its string value.

val:a number
Returns:a newly allocated string.

Function: xmlXPathCastStringToBoolean

int	xmlXPathCastStringToBoolean	(const xmlChar * val)

Converts a string to its boolean value

val:a string
Returns:the boolean value

Function: xmlXPathCastStringToNumber

double	xmlXPathCastStringToNumber	(const xmlChar * val)

Converts a string to its number value

val:a string
Returns:the number value

Function: xmlXPathCastToBoolean

int	xmlXPathCastToBoolean		(xmlXPathObjectPtr val)

Converts an XPath object to its boolean value

val:an XPath object
Returns:the boolean value

Function: xmlXPathCastToNumber

double	xmlXPathCastToNumber		(xmlXPathObjectPtr val)

Converts an XPath object to its number value

val:an XPath object
Returns:the number value

Function: xmlXPathCastToString

xmlChar *	xmlXPathCastToString	(xmlXPathObjectPtr val)

Converts an existing object to its string() equivalent

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().

Function: xmlXPathCmpNodes

int	xmlXPathCmpNodes		(xmlNodePtr node1, 
xmlNodePtr node2)

Compare two nodes w.r.t document order

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

Function: xmlXPathCompile

xmlXPathCompExprPtr	xmlXPathCompile	(const xmlChar * str)

Compile an XPath expression

str:the XPath expression
Returns:the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object.

Function: xmlXPathCompiledEval

xmlXPathObjectPtr	xmlXPathCompiledEval	(xmlXPathCompExprPtr comp, 
xmlXPathContextPtr ctx)

Evaluate the Precompiled XPath expression in the given context.

comp:the compiled XPath expression
ctx:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

Function: xmlXPathCompiledEvalToBoolean

int	xmlXPathCompiledEvalToBoolean	(xmlXPathCompExprPtr comp, 
xmlXPathContextPtr ctxt)

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

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.

Function: xmlXPathContextSetCache

int	xmlXPathContextSetCache		(xmlXPathContextPtr 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: 0: This will set the XPath object caching: @value: This will set the maximum number of XPath objects to be cached per slot There are 5 slots for: node-set, string, number, boolean, and misc objects. Use <0 for the default number (100). Other values for @options have currently no effect.

ctxt:the XPath context
active:enables/disables (creates/frees) the cache
value:a value with semantics dependant on @options
options:options (currently only the value 0 is used)
Returns:0 if the setting succeeded, and -1 on API or internal errors.

Function: xmlXPathConvertBoolean

xmlXPathObjectPtr	xmlXPathConvertBoolean	(xmlXPathObjectPtr val)

Converts an existing object to its boolean() equivalent

val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)

Function type: xmlXPathConvertFunc

Function type: xmlXPathConvertFunc
int	xmlXPathConvertFunc		(xmlXPathObjectPtr obj, 
int type)

A conversion function is associated to a type and used to cast the new type to primitive values.

obj:an XPath object
type:the number of the target type
Returns:-1 in case of error, 0 otherwise

Function: xmlXPathConvertNumber

xmlXPathObjectPtr	xmlXPathConvertNumber	(xmlXPathObjectPtr val)

Converts an existing object to its number() equivalent

val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)

Function: xmlXPathConvertString

xmlXPathObjectPtr	xmlXPathConvertString	(xmlXPathObjectPtr val)

Converts an existing object to its string() equivalent

val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)

Function: xmlXPathCtxtCompile

xmlXPathCompExprPtr	xmlXPathCtxtCompile	(xmlXPathContextPtr ctxt, 
const xmlChar * str)

Compile an XPath expression

ctxt:an XPath context
str:the XPath expression
Returns:the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object.

Function: xmlXPathEval

xmlXPathObjectPtr	xmlXPathEval	(const xmlChar * str, 
xmlXPathContextPtr ctx)

Evaluate the XPath Location Path in the given context.

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

Function: xmlXPathEvalExpression

xmlXPathObjectPtr	xmlXPathEvalExpression	(const xmlChar * str, 
xmlXPathContextPtr ctxt)

Evaluate the XPath expression in the given context.

str:the XPath expression
ctxt:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

Function type: xmlXPathEvalFunc

Function type: xmlXPathEvalFunc
void	xmlXPathEvalFunc		(xmlXPathParserContextPtr ctxt, 
int nargs)

An XPath evaluation function, the parameters are on the XPath context stack.

ctxt:an XPath parser context
nargs:the number of arguments passed to the function

Function: xmlXPathEvalPredicate

int	xmlXPathEvalPredicate		(xmlXPathContextPtr ctxt, 
xmlXPathObjectPtr 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.

ctxt:the XPath context
res:the Predicate Expression evaluation result
Returns:1 if predicate is true, 0 otherwise

Function: xmlXPathFreeCompExpr

void	xmlXPathFreeCompExpr		(xmlXPathCompExprPtr comp)

Free up the memory allocated by @comp

comp:an XPATH comp

Function: xmlXPathFreeContext

void	xmlXPathFreeContext		(xmlXPathContextPtr ctxt)

Free up an xmlXPathContext

ctxt:the context to free

Function: xmlXPathFreeNodeSet

void	xmlXPathFreeNodeSet		(xmlNodeSetPtr obj)

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

obj:the xmlNodeSetPtr to free

Function: xmlXPathFreeNodeSetList

void	xmlXPathFreeNodeSetList		(xmlXPathObjectPtr obj)

Free up the xmlXPathObjectPtr @obj but don't deallocate the objects in the list contrary to xmlXPathFreeObject().

obj:an existing NodeSetList object

Function: xmlXPathFreeObject

void	xmlXPathFreeObject		(xmlXPathObjectPtr obj)

Free up an xmlXPathObjectPtr object.

obj:the object to free

Function type: xmlXPathFuncLookupFunc

Function type: xmlXPathFuncLookupFunc
xmlXPathFunction	xmlXPathFuncLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri)

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

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.

Function type: xmlXPathFunction

Function type: xmlXPathFunction
void	xmlXPathFunction		(xmlXPathParserContextPtr 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.

ctxt:the XPath interprestation context
nargs:the number of arguments

Function: xmlXPathInit

void	xmlXPathInit			(void)

Initialize the XPath environment

Function: xmlXPathIsInf

int	xmlXPathIsInf			(double val)

Provides a portable isinf() function to detect whether a double is a +Infinite or -Infinite. Based on trio code http://sourceforge.net/projects/ctrio/

val:a double value
Returns:1 vi the value is +Infinite, -1 if -Infinite, 0 otherwise

Function: xmlXPathIsNaN

int	xmlXPathIsNaN			(double val)

Provides a portable isnan() function to detect whether a double is a NotaNumber. Based on trio code http://sourceforge.net/projects/ctrio/

val:a double value
Returns:1 if the value is a NaN, 0 otherwise

Function: xmlXPathNewContext

xmlXPathContextPtr	xmlXPathNewContext	(xmlDocPtr doc)

Create a new xmlXPathContext

doc:the XML document
Returns:the xmlXPathContext just allocated. The caller will need to free it.

Function: xmlXPathNodeSetCreate

xmlNodeSetPtr	xmlXPathNodeSetCreate	(xmlNodePtr val)

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

val:an initial xmlNodePtr, or NULL
Returns:the newly created object.

Function: xmlXPathObjectCopy

xmlXPathObjectPtr	xmlXPathObjectCopy	(xmlXPathObjectPtr val)

allocate a new copy of a given object

val:the original object
Returns:the newly created object.

Function: xmlXPathOrderDocElems

long	xmlXPathOrderDocElems		(xmlDocPtr doc)

Call this routine to speed up XPath computation on static documents. 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.

doc:an input document
Returns:the number of elements found in the document or -1 in case of error.

Function type: xmlXPathVariableLookupFunc

Function type: xmlXPathVariableLookupFunc
xmlXPathObjectPtr	xmlXPathVariableLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri)

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

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.

Daniel Veillard