Feature Element Paths
Functions introduced:
An element path is used to describe the location of an element in an element tree. It is used by some of the ProElement functions as a convenient way to refer to elements already in a tree.
The object ProElempath is declared as an opaque pointer. It contains a description of the path from the root of the tree down to the element referred to. At most levels in the tree hierarchy, the relevant path member is the element ID of the element (which is unique at that level). When the path steps from an array element to one of its member arrays, the element path instead contains the array index of that element.
To be able to set the value of a ProElempath, provides a structure called ProElempathItem that can describe an element ID, or the index into an array element. An array of ProElempathItem structures is therefore a visible equivalent to the opaque contents of ProElempath.
The declaration of ProElempathItem is as follows:
typedef struct path
{
ProElempathItemtype type;
union
{
int elem_id;
int elem_index;
} path_item;
} ProElempathItem;
typedef enum
{
PRO_ELEM_PATH_ITEM_TYPE_ID,
PRO_ELEM_PATH_ITEM_TYPE_INDEX
} ProElempathItemtype;
The object ProElempath, the structure ProElempathItem, and all the functions in this section are declared in the header file ProElempath.h.
The function
ProElempathAlloc() allocates a new empty
ProElempath object, whereas
ProElempathFree() frees a
ProElempath.
The function
ProElempathDataSet() enables you to set the contents of a
ProElempath by copying from an array of
ProElempathItem structures.
The function
ProElempathDataGet() reads the contents of a
ProElempath into an array of
ProElempathItem structures. The array is an expandable array that must be allocated by a call to
ProArrayAlloc() before you call the function.
The function
ProElempathCopy() copies the contents of one
ProElempath object into another. The output object is allocated by the function.
The function
ProElempathCompare() tells you whether two
ProElempath objects refer to the same element.
The function
ProElempathSizeGet() tells you the length of the element path contained in a
ProElempath object.