* $Id$\r
*/\r
\r
-\r
/*\r
* Abstract:\r
* Declaration of flexi map, a binary tree where the caller always provides\r
* all necessary storage.\r
- *\r
- * Environment:\r
- * All\r
*/\r
\r
-\r
#ifndef _CL_FLEXIMAP_H_\r
#define _CL_FLEXIMAP_H_\r
\r
-\r
#include <complib/cl_qmap.h>\r
\r
+#ifdef __cplusplus\r
+# define BEGIN_C_DECLS extern "C" {\r
+# define END_C_DECLS }\r
+#else /* !__cplusplus */\r
+# define BEGIN_C_DECLS\r
+# define END_C_DECLS\r
+#endif /* __cplusplus */\r
+\r
+BEGIN_C_DECLS\r
\r
/****h* Component Library/Flexi Map\r
* NAME\r
*\r
* DESCRIPTION\r
* Flexi map implements a binary tree that stores user provided cl_fmap_item_t\r
-* structures. Each item stored in a flexi map has a unique user defined key\r
-* (duplicates are not allowed). Flexi map provides the ability to\r
-* efficiently search for an item given a key. Flexi map allows user defined\r
-* keys of any size. Storage for keys and a comparisson function are provided\r
-* by users to allow flexi map to store items with arbitrary key values.\r
+* structures. Each item stored in a flexi map has a unique user defined\r
+* key (duplicates are not allowed). Flexi map provides the ability to\r
+* efficiently search for an item given a key. Flexi map allows user\r
+* defined keys of any size. Storage for keys and a comparison function\r
+* are provided by users to allow flexi map to store items with arbitrary\r
+* key values.\r
*\r
* Flexi map does not allocate any memory, and can therefore not fail\r
* any operations due to insufficient memory. Flexi map can thus be useful\r
*\r
* Manipulation:\r
* cl_fmap_insert, cl_fmap_get, cl_fmap_remove_item, cl_fmap_remove,\r
-* cl_fmap_remove_all, cl_fmap_merge, cl_fmap_delta\r
+* cl_fmap_remove_all, cl_fmap_merge, cl_fmap_delta, cl_fmap_get_next\r
*\r
* Search:\r
* cl_fmap_apply_func\r
* cl_fmap_count, cl_is_fmap_empty,\r
*********/\r
\r
-\r
/****s* Component Library: Flexi Map/cl_fmap_item_t\r
* NAME\r
* cl_fmap_item_t\r
* Flexi Map, cl_fmap_insert, cl_fmap_key, cl_pool_item_t, cl_list_item_t\r
*********/\r
\r
-\r
/****d* Component Library: Flexi Map/cl_pfn_fmap_cmp_t\r
* NAME\r
* cl_pfn_fmap_cmp_t\r
*\r
* RETURN VALUE\r
* Returns 0 if the keys match.\r
-* Returns less than 0 if p_key1 is less than p_key2.\r
-* Returns greater than 0 if p_key1 is greater than p_key2.\r
+* Returns less than 0 if *p_key1 is less than *p_key2.\r
+* Returns greater than 0 if *p_key1 is greater than *p_key2.\r
*\r
* NOTES\r
* This function type is provided as function prototype reference for the\r
* Flexi Map, cl_fmap_init\r
*********/\r
\r
-\r
/****s* Component Library: Flexi Map/cl_fmap_t\r
* NAME\r
* cl_fmap_t\r
* Flexi Map, cl_pfn_fmap_cmp_t\r
*********/\r
\r
-\r
/****d* Component Library: Flexi Map/cl_pfn_fmap_apply_t\r
* NAME\r
* cl_pfn_fmap_apply_t\r
* Flexi Map, cl_fmap_apply_func\r
*********/\r
\r
-\r
-#ifdef __cplusplus\r
-extern "C" {\r
-#endif\r
-\r
-\r
/****f* Component Library: Flexi Map/cl_fmap_count\r
* NAME\r
* cl_fmap_count\r
* Flexi Map, cl_fmap_remove, cl_fmap_item_t\r
*********/\r
\r
+/****f* Component Library: Flexi Map/cl_fmap_match\r
+* NAME\r
+* cl_fmap_match\r
+*\r
+* DESCRIPTION\r
+* The cl_fmap_match function returns the map item matching a key.\r
+*\r
+* SYNOPSIS\r
+*/\r
+CL_EXPORT cl_fmap_item_t* CL_API\r
+cl_fmap_match(\r
+ IN const cl_fmap_t * const p_map,\r
+ IN const void *const p_key,\r
+ IN cl_pfn_fmap_cmp_t pfn_compare );\r
+/*\r
+* PARAMETERS\r
+* p_map\r
+* [in] Pointer to a cl_fmap_t structure from which to retrieve the\r
+* item with the specified key.\r
+*\r
+* p_key\r
+* [in] Pointer to a key value used to search for the desired map item.\r
+*\r
+* pfn_compare\r
+* [in] Pointer to a compare function to invoke to compare the\r
+* keys of items in the map. Passing NULL here makes such call\r
+* to be equivalent to using cl_fmap_get().\r
+*\r
+* RETURN VALUES\r
+* Pointer to the map item matching the desired key value.\r
+*\r
+* Pointer to the map end if there was no item matching the desired key\r
+* value stored in the flexi map.\r
+*\r
+* SEE ALSO\r
+* Flexi Map, cl_fmap_remove, cl_fmap_get\r
+*********/\r
\r
/****f* Component Library: Flexi Map/cl_fmap_get\r
* NAME\r
* cl_fmap_get does not remove the item from the flexi map.\r
*\r
* SEE ALSO\r
-* Flexi Map, cl_fmap_remove\r
+* Flexi Map, cl_fmap_remove, cl_fmap_get_next\r
*********/\r
\r
+/****f* Component Library: Flexi Map/cl_fmap_get_next\r
+* NAME\r
+* cl_fmap_get_next\r
+*\r
+* DESCRIPTION\r
+* The cl_fmap_get_next function returns the first map item associated with a\r
+* key > the key specified.\r
+*\r
+* SYNOPSIS\r
+*/\r
+CL_EXPORT cl_fmap_item_t* CL_API\r
+cl_fmap_get_next(\r
+ IN const cl_fmap_t * const p_map,\r
+ IN const void *const p_key );\r
+/*\r
+* PARAMETERS\r
+* p_map\r
+* [in] Pointer to a cl_fmap_t structure from which to retrieve the\r
+* item with the specified key.\r
+*\r
+* p_key\r
+* [in] Pointer to a key value used to search for the desired map item.\r
+*\r
+* RETURN VALUES\r
+* Pointer to the first map item with a key > the desired key value.\r
+*\r
+* Pointer to the map end if there was no item with a key > the desired key\r
+* value stored in the flexi map.\r
+*\r
+* NOTES\r
+* cl_fmap_get_next does not remove the item from the flexi map.\r
+*\r
+* SEE ALSO\r
+* Flexi Map, cl_fmap_remove, cl_fmap_get\r
+*********/\r
\r
/****f* Component Library: Flexi Map/cl_fmap_remove_item\r
* NAME\r
* Items are evaluated based on their keys. Items that exist in both\r
* p_map1 and p_map2 remain in their respective maps. Items that\r
* exist only p_map1 are moved to p_old. Likewise, items that exist only\r
-* in p_map2 are moved to p_new. This function can be usefull in evaluating\r
+* in p_map2 are moved to p_new. This function can be useful in evaluating\r
* changes between two maps.\r
*\r
* Both maps pointed to by p_new and p_old must be empty on input. This\r
* Flexi Map, cl_pfn_fmap_apply_t\r
*********/\r
\r
-#ifdef __cplusplus\r
-}\r
-#endif\r
-\r
+END_C_DECLS\r
\r
#endif /* _CL_FLEXIMAP_H_ */\r
projects / ~shefty / rdma-win.git / commitdiff