Indexing

Mini-XML provides functions for managing indices of nodes. The current implementation provides the same functionality as the mxmlFindElement(). The advantage of using an index is that searching and enumeration of elements is significantly faster. The only disadvantage is that each index is a static snapshot of the XML document, so indices are not well suited to XML data that is updated more often than it is searched. The overhead of creating an index is approximately equal to walking the XML document tree. Nodes in the index are sorted by element name and attribute value.

Indices are stored in mxml_index_t structures. The mxmlIndexNew() function creates a new index:

    mxml_node_t *tree;
    mxml_index_t *ind;

    ind = mxmlIndexNew(tree, "element", "attribute");

The first argument is the XML node tree to index. Normally this will be a pointer to the ?xml element.

The second argument contains the element to index; passing NULL indexes all element nodes alphabetically.

The third argument contains the attribute to index; passing NULL causes only the element name to be indexed.

Once the index is created, the mxmlIndexEnum(), mxmlIndexFind(), and mxmlIndexReset() functions are used to access the nodes in the index. The mxmlIndexReset() function resets the "current" node pointer in the index, allowing you to do new searches and enumerations on the same index. Typically you will call this function prior to your calls to mxmlIndexEnum() and mxmlIndexFind().

The mxmlIndexEnum() function enumerates each of the nodes in the index and can be used in a loop as follows:

    mxml_node_t *node;
    mxml_index_t *ind;

    mxmlIndexReset(ind);

    while ((node = mxmlIndexEnum(ind)) != NULL)
    {
      // do something with node
    }

The mxmlIndexFind() function locates the next occurrence of the named element and attribute value in the index. It can be used to find all matching elements in an index, as follows:

    mxml_node_t *node;
    mxml_index_t *ind;

    mxmlIndexReset(ind);

    while ((node = mxmlIndexFind(ind, "element", "attr-value")) != NULL)
    {
      // do something with node
    }

The second and third arguments represent the element name and attribute value, respectively. A NULL pointer is used to return all elements or attributes in the index. Passing NULL for both the element name and attribute value is equivalent to calling mxmlIndexEnum.

When you are done using the index, delete it using the mxmlIndexDelete() function:

    mxml_index_t *ind;

    mxmlIndexDelete(ind);