|
|
/*
* tree.h * * data type providing a map from a key to a value, where the value is * an arbitrary area of storage. * * The current implementation of this is a binary search tree with no * balancing, so it will be inefficient if the data is presented in * strict ascending or descending order. * * all memory is allocated from a gmem_* heap that is passed on * creation of the tree. * * include gutils.h before this. */
/* handle for a tree */typedef struct tree FAR * TREE;
/* keys in these trees are DWORDs */typedef DWORD TREEKEY;
/* some sort of place-holder understood only by tree_search and
* tree_addafter */typedef struct treeitem FAR * TREEITEM;
/* pointer to one of these place holders */typedef TREEITEM FAR * PTREEITEM;
/*
* create an empty tree and return a handle to it. Pass the heap to * be used for all memory allocations. */TREE APIENTRY tree_create(HANDLE hHeap);
/* delete a tree and discard any associated memory. The tree need not be
* empty. This will discard the elements of the tree; but if these * contained pointers to further data blocks, these will not be discarded- * you must free these before deleting the tree. */void APIENTRY tree_delete(TREE tree);
/* add new element to the tree, mapping the key given to the value
* * a block of data of length bytes will be inserted in the tree, mapped * to this key, a pointer to this block will be returned. if the * value pointer is non-null, the block value[0..length-1] will be copied * to the new block. * * if the key already exists, the value block will be replaced with the * new size and (if value is non-null) contents. */LPVOID APIENTRY tree_update(TREE tree, TREEKEY key, LPVOID value, UINT length);
/* return a pointer to the value associated with a given key in this tree.
* returns NULL if the key is not found. */LPVOID APIENTRY tree_find(TREE tree, TREEKEY key);
/*
* a common tree operation is to insert a new element into the * tree only if that key is not found, and otherwise to update in some * way the existing value. Using the standard functions above, that * would require one lookup for the tree_find, and then a second lookup * to insert the new element. * * the two functions below provide an optimisation over this. tree_search * will return the value if found; if not, it will return NULL, and set * pitem to a pointer to a place holder in the tree where the item * should be inserted. tree_addafter takes this placeholder as * an argument, and will insert the key/value in the tree at that point. * * as for tree_update, the value pointer can be NULL - in this case * the block is allocated on the tree, but not initialised. * * the return value from tree_addafter is a pointer to the value block in * the tree */LPVOID APIENTRY tree_search(TREE tree, TREEKEY key, PTREEITEM place);
LPVOID APIENTRY tree_addafter(TREE tree, PTREEITEM place, TREEKEY key, LPVOID value, UINT length);
/* -- ctree ---------------
* * this is a type of tree based on the tree_ data type above, that implements * counting for insertions of identical keys. * * ctree_update, if the key is unique, will insert the object and set the count * to 1. if the key is not unique, it will just increment the reference count. * * ctree_getcount returns the reference count for a tree. * ctree_find returns the first value inserted for that key, if any */
/*
* create an empty counting-tree and return handle. pass in the gmem_init() * heap to be used for all memory allocations. */TREE APIENTRY ctree_create(HANDLE hHeap);
/*
* delete a tree and all memory associated directly with it. */void APIENTRY ctree_delete(TREE tree);
/*
* if the KEY is unique within the tree, insert the value and * set the count for that key to 1. If the key is not unique, add one to * the reference count for that key but leave the value untouched. */LPVOID APIENTRY ctree_update(TREE tree, TREEKEY key, LPVOID value, UINT length);
/*
* find the reference count for the given key */long APIENTRY ctree_getcount(TREE tree, TREEKEY key);
/*
* return the value for the given key (note this will be the value for * the first insertion of this key */LPVOID APIENTRY ctree_find(TREE tree, TREEKEY key);
|
