/*
 * File: ttt.h
 * -----------
 * This file provides an interface for a general 2-3 search
 * tree facility that allows the client to maintain control of
 * the structure of the node.
 */

#ifndef _ttt_h
#define _ttt_h

#include "genlib.h"

/* Types: clientDataT, keyT, clientBlockT
 * --------------------------------------
 * These are all void*, but to emphasize the reasons for the void*,
 * keyT is used for keys. 
 * clientBlockT for the blocks of memory
 * (allocated by the client) stored in the tree.  These blocks must
 * include both a key and the data assoiciated with the key.
 * clientDataT is used for any additional piece of data which client
 * might pass along to callback functions.
 */
typedef void *clientDataT, *keyT, *clientBlockT;


/*
 * Type: tttADT
 * ------------
 * This is the abstract type for a 2-3 tree.
 */

typedef struct tttCDT *tttADT;


/*
 * Type: compFnT
 * ------------
 * This type defines the type space of comparison functions.
 * Both arguments to compare functions are void*, but the following
 * convention will be used: the first argument is always an "isolated" key,
 * the second takes the address a client allocated block of memory
 * which contains a key.  The two keys are compared and an integer
 * is returned which is negative, 0, or positive depending on
 * whether the first key is less than, equal to, or
 * greater than the second.
 *
 */

typedef int (*compFnT)(const keyT p1, const clientBlockT p2);


/*
 * Type: nodeFnT
 * -------------
 * This type defines the class of callback functions for nodes.
 */

typedef void (*nodeFnT)(clientBlockT blockPtr, clientDataT clientData);


/*
 * Function: NewTTT
 * Usage: ttt = NewTTT(compFn);
 * -------------------------------------------------------
 * This function allocates and returns a new empty 2-3
 * tree.  The argument is a comparison function. 
 */

tttADT NewTTT(compFnT compFn);

/*
 * Function: FindTTTNode
 * Usage: np = FindTTTNode(ttt, key);
 * -----------------------------------
 * This function applies the 2-3 search algorithm to find a
 * particular key in the tree represented by ttt.  The second
 * argument represents the address of the key in the client
 * space rather than the key itself, which makes it possible to
 * use this package for keys that are not pointer types.  If a
 * node matching the key appears in the tree, FindTTTNode
 * returns a pointer to it; if not, FindTTTNode returns NULL.
 */

clientBlockT FindTTTNode(tttADT ttt, keyT kp);

/*
 * Function: InsertTTTNode
 * Usage: np = InsertTTTNode(ttt, key, clientBlock);
 * -------------------------------------------------
 * This function is used to insert a new client block into a 2-3
 * tree.  The ttt and key arguments are interpreted as they are
 * in FindTTTNode.  If the key already exists, the associated client
 * block is overwritten.  If the key is not found, then the clientBlock 
 * is added to the tree.  
 */

void InsertTTTNode(tttADT ttt, keyT kp, clientBlockT clientBlock);


/*
 * Function: MapTTT
 * Usage: MapTTT(fn, ttt, order, clientData);
 * ------------------------------------------
 * This function calls fn on every node in the 2-3 tree,
 * passing it a pointer to a node and the clientData pointer.  The
 * type of traversal is given by the order argument, which must
 * be one of the constants InOrder, PreOrder, or PostOrder.
 */

typedef enum { InOrder, PreOrder, PostOrder } traversalOrderT;

void MapTTT(nodeFnT fn, tttADT ttt, traversalOrderT order,
            clientDataT clientData);


/*
 * Note: it is possible to implement functions for deleting and freeing,
 * but you are not required to do so.  Also, note that this implementation
 * may leak memory when an item is added which has a key which is already
 * in the tree.
 */

#endif