## xpath

xpath —

## Synopsis

    struct      xmlXPathContext;
    typedef     xmlXPathContextPtr;
    struct      xmlXPathParserContext;
    typedef     xmlXPathParserContextPtr;
    enum        xmlXPathError;
    struct      xmlNodeSet;
    typedef     xmlNodeSetPtr;
    enum        xmlXPathObjectType;
    struct      xmlXPathObject;
    typedef     xmlXPathObjectPtr;
    int         (*xmlXPathConvertFunc)          (xmlXPathObjectPtr obj,
                                                 int type);
    struct      xmlXPathType;
    typedef     xmlXPathTypePtr;
    struct      xmlXPathVariable;
    typedef     xmlXPathVariablePtr;
    void        (*xmlXPathEvalFunc)             (xmlXPathParserContextPtr ctxt,
                                                 int nargs);
    struct      xmlXPathFunct;
    typedef     xmlXPathFuncPtr;
    xmlXPathObjectPtr (*xmlXPathAxisFunc)       (xmlXPathParserContextPtr ctxt,
                                                 xmlXPathObjectPtr cur);
    struct      xmlXPathAxis;
    typedef     xmlXPathAxisPtr;
    struct      xmlXPathCompExpr;
    typedef     xmlXPathCompExprPtr;
    void        (*xmlXPathFunction)             (xmlXPathParserContextPtr ctxt,
                                                 int nargs);
    int         xmlXPathIsNaN                   (double val);
    int         xmlXPathIsInf                   (double val);
    #define     xmlXPathNodeSetGetLength        (ns)
    #define     xmlXPathNodeSetItem             (ns, index)
    #define     xmlXPathNodeSetIsEmpty          (ns)
    void        xmlXPathFreeObject              (xmlXPathObjectPtr obj);
    xmlNodeSetPtr xmlXPathNodeSetCreate         (xmlNodePtr val);
    void        xmlXPathFreeNodeSetList         (xmlXPathObjectPtr obj);
    void        xmlXPathFreeNodeSet             (xmlNodeSetPtr obj);
    xmlXPathObjectPtr xmlXPathObjectCopy        (xmlXPathObjectPtr val);
    int         xmlXPathCmpNodes                (xmlNodePtr node1,
                                                 xmlNodePtr node2);
    int         xmlXPathCastNumberToBoolean     (double val);
    int         xmlXPathCastStringToBoolean     (const xmlChar *val);
    int         xmlXPathCastNodeSetToBoolean    (xmlNodeSetPtr ns);
    int         xmlXPathCastToBoolean           (xmlXPathObjectPtr val);
    double      xmlXPathCastBooleanToNumber     (int val);
    double      xmlXPathCastStringToNumber      (const xmlChar *val);
    double      xmlXPathCastNodeToNumber        (xmlNodePtr node);
    double      xmlXPathCastNodeSetToNumber     (xmlNodeSetPtr ns);
    double      xmlXPathCastToNumber            (xmlXPathObjectPtr val);
    xmlChar*    xmlXPathCastBooleanToString     (int val);
    xmlChar*    xmlXPathCastNumberToString      (double val);
    xmlChar*    xmlXPathCastNodeToString        (xmlNodePtr node);
    xmlChar*    xmlXPathCastNodeSetToString     (xmlNodeSetPtr ns);
    xmlChar*    xmlXPathCastToString            (xmlXPathObjectPtr val);
    xmlXPathObjectPtr xmlXPathConvertBoolean    (xmlXPathObjectPtr val);
    xmlXPathObjectPtr xmlXPathConvertNumber     (xmlXPathObjectPtr val);
    xmlXPathObjectPtr xmlXPathConvertString     (xmlXPathObjectPtr val);
    void        xmlXPathInit                    (void);
    xmlXPathContextPtr xmlXPathNewContext       (xmlDocPtr doc);
    void        xmlXPathFreeContext             (xmlXPathContextPtr ctxt);
    long        xmlXPathOrderDocElems           (xmlDocPtr doc);
    xmlXPathObjectPtr xmlXPathEval              (const xmlChar *str,
                                                 xmlXPathContextPtr ctx);
    xmlXPathObjectPtr xmlXPathEvalExpression    (const xmlChar *str,
                                                 xmlXPathContextPtr ctxt);
    int         xmlXPathEvalPredicate           (xmlXPathContextPtr ctxt,
                                                 xmlXPathObjectPtr res);
    xmlXPathCompExprPtr xmlXPathCompile         (const xmlChar *str);
    xmlXPathObjectPtr xmlXPathCompiledEval      (xmlXPathCompExprPtr comp,
                                                 xmlXPathContextPtr ctx);
    void        xmlXPathFreeCompExpr            (xmlXPathCompExprPtr comp);

## Description

## Details

### struct 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 nodes of the context node */
        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 XPointer */
        int xptr;				/* it this an XPointer context */
        xmlNodePtr here;			/* for here() */
        xmlNodePtr origin;			/* for origin() */

        /* the set of namespace declarations in scope for the expression */
        xmlHashTablePtr nsHash;		/* The namespaces hash table */
        void *varLookupFunc;		/* variable lookup func */
        void *varLookupData;		/* variable lookup data */

        /* Possibility to link in an extra item */
        void *extra;                        /* needed for XSLT */

        /* The function name and URI when calling a function */
        const xmlChar *function;
        const xmlChar *functionURI;

        /* function lookup function and data */
        void *funcLookupFunc;		/* function lookup func */
        void *funcLookupData;		/* function lookup data */

        /* temporary namespace lists kept for walking the namespace axis */
        xmlNsPtr *tmpNsList;		/* Array of namespaces */
        int tmpNsNr;			/* number of namespace in scope */
    };

Expression evaluation occurs with respect to a context. he context consists of: - a node (the context node) - a node list (the context node list) - a set of variable bindings - a function library - the set of namespace declarations in scope for the expression Following the switch to hash tables, this need to be trimmed up at the next binary incompatible release.

### xmlXPathContextPtr

    typedef xmlXPathContext *xmlXPathContextPtr;

### struct 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 */
    };

An XPath parser context. It contains pure parsing informations, an xmlXPathContext, and the stack of objects.

### xmlXPathParserContextPtr

    typedef xmlXPathParserContext *xmlXPathParserContextPtr;

### enum xmlXPathError

    typedef enum {
        XPATH_EXPRESSION_OK = 0,
        XPATH_NUMBER_ERROR,
        XPATH_UNFINISHED_LITERAL_ERROR,
        XPATH_START_LITERAL_ERROR,
        XPATH_VARIABLE_REF_ERROR,
        XPATH_UNDEF_VARIABLE_ERROR,
        XPATH_INVALID_PREDICATE_ERROR,
        XPATH_EXPR_ERROR,
        XPATH_UNCLOSED_ERROR,
        XPATH_UNKNOWN_FUNC_ERROR,
        XPATH_INVALID_OPERAND,
        XPATH_INVALID_TYPE,
        XPATH_INVALID_ARITY,
        XPATH_INVALID_CTXT_SIZE,
        XPATH_INVALID_CTXT_POSITION,
        XPATH_MEMORY_ERROR,
        XPTR_SYNTAX_ERROR,
        XPTR_RESOURCE_ERROR,
        XPTR_SUB_RESOURCE_ERROR,
        XPATH_UNDEF_PREFIX_ERROR,
        XPATH_ENCODING_ERROR,
        XPATH_INVALID_CHAR_ERROR
    } xmlXPathError;

### struct 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 */
        /* @@ with_ns to check wether namespace nodes should be looked at @@ */
    };

### xmlNodeSetPtr

    typedef xmlNodeSet *xmlNodeSetPtr;

### enum xmlXPathObjectType

    typedef enum {
        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 */
    } xmlXPathObjectType;

### struct xmlXPathObject

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

### xmlXPathObjectPtr

    typedef xmlXPathObject *xmlXPathObjectPtr;

### 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

### struct xmlXPathType

    struct xmlXPathType {
        const xmlChar         *name;		/* the type name */
        xmlXPathConvertFunc func;		/* the conversion function */
    };

### xmlXPathTypePtr

    typedef xmlXPathType *xmlXPathTypePtr;

### struct xmlXPathVariable

    struct xmlXPathVariable {
        const xmlChar       *name;		/* the variable name */
        xmlXPathObjectPtr value;		/* the value */
    };

### xmlXPathVariablePtr

    typedef xmlXPathVariable *xmlXPathVariablePtr;

### 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

### struct xmlXPathFunct

    struct xmlXPathFunct {
        const xmlChar      *name;		/* the function name */
        xmlXPathEvalFunc func;		/* the evaluation function */
    };

### xmlXPathFuncPtr

    typedef xmlXPathFunct *xmlXPathFuncPtr;

### 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.

### struct xmlXPathAxis

    struct xmlXPathAxis {
        const xmlChar      *name;		/* the axis name */
        xmlXPathAxisFunc func;		/* the search function */
    };

### xmlXPathAxisPtr

    typedef xmlXPathAxis *xmlXPathAxisPtr;

### struct xmlXPathCompExpr

    struct xmlXPathCompExpr;

### xmlXPathCompExprPtr

    typedef xmlXPathCompExpr *xmlXPathCompExprPtr;

### 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

### 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

### 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

### xmlXPathNodeSetGetLength()

    #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)

Implement a functionality similar to the DOM NodeList.length.

`ns` : | a node-set

### xmlXPathNodeSetItem()

    #define     xmlXPathNodeSetItem(ns, index)

Implements a functionality similar to the DOM NodeList.item().

`ns` : | a node-set
`index` : | index of a node in the set

### xmlXPathNodeSetIsEmpty()

    #define     xmlXPathNodeSetIsEmpty(ns)

Checks whether `ns` is empty or not.

`ns` : | a node-set

### xmlXPathFreeObject ()

    void        xmlXPathFreeObject              (xmlXPathObjectPtr obj);

Free up an xmlXPathObjectPtr object.

`obj` : | the object to free

### 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.

### 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

### xmlXPathFreeNodeSet ()

    void        xmlXPathFreeNodeSet             (xmlNodeSetPtr obj);

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

`obj` : | the xmlNodeSetPtr to free

### xmlXPathObjectCopy ()

    xmlXPathObjectPtr xmlXPathObjectCopy        (xmlXPathObjectPtr val);

allocate a new copy of a given object

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

### 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 that's the same node, -1 otherwise

### xmlXPathCastNumberToBoolean ()

    int         xmlXPathCastNumberToBoolean     (double val);

Converts a number to its boolean value

`val` : | a number
Returns : | the boolean value

### xmlXPathCastStringToBoolean ()

    int         xmlXPathCastStringToBoolean     (const xmlChar *val);

Converts a string to its boolean value

`val` : | a string
Returns : | the boolean value

### xmlXPathCastNodeSetToBoolean ()

    int         xmlXPathCastNodeSetToBoolean    (xmlNodeSetPtr ns);

Converts a node-set to its boolean value

`ns` : | a node-set
Returns : | the boolean value

### xmlXPathCastToBoolean ()

    int         xmlXPathCastToBoolean           (xmlXPathObjectPtr val);

Converts an XPath object to its boolean value

`val` : | an XPath object
Returns : | the boolean value

### xmlXPathCastBooleanToNumber ()

    double      xmlXPathCastBooleanToNumber     (int val);

Converts a boolean to its number value

`val` : | a boolean
Returns : | the number value

### xmlXPathCastStringToNumber ()

    double      xmlXPathCastStringToNumber      (const xmlChar *val);

Converts a string to its number value

`val` : | a string
Returns : | the number value

### xmlXPathCastNodeToNumber ()

    double      xmlXPathCastNodeToNumber        (xmlNodePtr node);

Converts a node to its number value

`node` : | a node
Returns : | the number value

### xmlXPathCastNodeSetToNumber ()

    double      xmlXPathCastNodeSetToNumber     (xmlNodeSetPtr ns);

Converts a node-set to its number value

`ns` : | a node-set
Returns : | the number value

### xmlXPathCastToNumber ()

    double      xmlXPathCastToNumber            (xmlXPathObjectPtr val);

Converts an XPath object to its number value

`val` : | an XPath object
Returns : | the number value

### xmlXPathCastBooleanToString ()

    xmlChar*    xmlXPathCastBooleanToString     (int val);

Converts a boolean to its string value.

`val` : | a boolean
Returns : | a newly allocated string.

### xmlXPathCastNumberToString ()

    xmlChar*    xmlXPathCastNumberToString      (double val);

Converts a number to its string value.

`val` : | a number
Returns : | a newly allocated string.

### xmlXPathCastNodeToString ()

    xmlChar*    xmlXPathCastNodeToString        (xmlNodePtr node);

Converts a node to its string value.

`node` : | a node
Returns : | a newly allocated string.

### xmlXPathCastNodeSetToString ()

    xmlChar*    xmlXPathCastNodeSetToString     (xmlNodeSetPtr ns);

Converts a node-set to its string value.

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

### xmlXPathCastToString ()

    xmlChar*    xmlXPathCastToString            (xmlXPathObjectPtr val);

Converts an existing object to its string() equivalent

`val` : | an XPath object
Returns : | the string value of the object, NULL in case of error. A new string is allocated only if needed (`val` isn't a string object).

### 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`)

### 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`)

### 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`)

### xmlXPathInit ()

    void        xmlXPathInit                    (void);

Initialize the XPath environment

### 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.

### xmlXPathFreeContext ()

    void        xmlXPathFreeContext             (xmlXPathContextPtr ctxt);

Free up an xmlXPathContext

`ctxt` : | the context to free

### 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 (startting at -1) to be able to differenciate from line numbers.

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

### 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.

### 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.

### 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

### 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.

### 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.

### xmlXPathFreeCompExpr ()

    void        xmlXPathFreeCompExpr            (xmlXPathCompExprPtr comp);

Free up the memory allocated by `comp`

`comp` : | an XPATH comp