From: Adam Dickmeiss <adam@indexdata.dk>
Date: Tue, 29 Aug 2006 11:28:42 +0000 (+0000)
Subject: More comments on dict.h. Moved typedef Dict_ptr to private dict header.
X-Git-Tag: ZEBRA.2.0.2~43
X-Git-Url: http://git.indexdata.com/?p=idzebra-moved-to-github.git;a=commitdiff_plain;h=1f61b7e564e0ed44176f4c26302c828c45dd121c

More comments on dict.h. Moved typedef Dict_ptr to private dict header.
---

diff --git a/dict/dict-p.h b/dict/dict-p.h
index 4ba0fdf..64b4082 100644
--- a/dict/dict-p.h
+++ b/dict/dict-p.h
@@ -1,4 +1,4 @@
-/* $Id: dict-p.h,v 1.6 2006-08-29 09:27:55 adam Exp $
+/* $Id: dict-p.h,v 1.7 2006-08-29 11:28:42 adam Exp $
    Copyright (C) 1995-2006
    Index Data ApS
 
@@ -34,6 +34,7 @@ YAZ_BEGIN_CDECL
 #define DICT_DEFAULT_PAGESIZE 4096
 
 typedef unsigned char Dict_char;
+typedef unsigned Dict_ptr;
 
 struct Dict_head {
     char magic_str[8];
diff --git a/include/idzebra/dict.h b/include/idzebra/dict.h
index 11209d0..54c9c80 100644
--- a/include/idzebra/dict.h
+++ b/include/idzebra/dict.h
@@ -1,4 +1,4 @@
-/* $Id: dict.h,v 1.7 2006-08-29 09:27:56 adam Exp $
+/* $Id: dict.h,v 1.8 2006-08-29 11:28:44 adam Exp $
    Copyright (C) 1995-2006
    Index Data ApS
 
@@ -37,53 +37,139 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 YAZ_BEGIN_CDECL
 
 /** \var Dict
- * \brief Dictionary type
+ * \brief Dictionary handle
  *
  * Most dictionary functions operatate on a Dict type (object).
  */
 typedef struct Dict_struct *Dict;
 
-typedef unsigned Dict_ptr;
-
+/** \brief open dictionary
+    \param bfs block file storage
+    \param name name of dictionary file
+    \param cache number of pages to cache
+    \param rw 0=read-only, 1=read&write
+    \param compact_flag 1=write with compact, 0=normal paged operation
+    \param page_size page size of disc block
+    \returns dictionary handle
+*/
 YAZ_EXPORT 
-Dict dict_open (BFiles bfs, const char *name, int cache, int rw,
-		      int compact_flag, int page_size);
+Dict dict_open(BFiles bfs, const char *name, int cache, int rw,
+               int compact_flag, int page_size);
 
+/** \brief closes dictionary
+    \param dict handle
+    \retval 0 OK
+    \retval -1 failure
+*/
 YAZ_EXPORT
-int dict_close (Dict dict);
-
+int dict_close(Dict dict);
+
+/** \brief insert item into dictionary
+    \param dict dictionary handle
+    \param p string-z with lookup string
+    \param userlen length of user data (associated with p)
+    \param userinfo userdata (of size userlen)
+    \retval 0 p is new and inserted OK
+    \retval 1 p is updated (already exists) and userinfo is modified
+    \retval 2 p already exists and userinfo is unmodified (same as before)
+    \retval -1 error
+*/
 YAZ_EXPORT
-int dict_insert (Dict dict, const char *p, int userlen, void *userinfo);
-
+int dict_insert(Dict dict, const char *p, int userlen, void *userinfo);
+
+/** \brief deletes item from dictionary
+    \param dict dictionary handle
+    \param p string-z with lookup string
+    \retval 0 p not found
+    \retval 1 p found and deleted
+    \retval -1 error
+*/
 YAZ_EXPORT
-int dict_delete (Dict dict, const char *p);
+int dict_delete(Dict dict, const char *p);
 
+/** \brief lookup item in dictionary
+    \param dict dictionary handle
+    \param p string-z with lookup string
+    \retval NULL not found
+    \retval value where value[0]=userlen, value[1..userlen] is userinfo data
+*/
 YAZ_EXPORT
-int dict_delete_subtree (Dict dict, const char *p, void *client,
-				int (*f)(const char *info, void *client));
+char *dict_lookup(Dict dict, const char *p);
+
+/** \brief delete items with a given prefix from dictionary
+    \param dict dictionary handle
+    \param p string-z with prefix
+    \param client client data to be supplied to function f
+    \param f function which gets called for each item in tree
+    \retval 0 OK (0 or  more entries deleted)
+    \retval 1 OK (1 or more entries delete)
+    \retval -1 ERROR
+*/
 YAZ_EXPORT
-char *dict_lookup (Dict dict, const char *p);
+int dict_delete_subtree(Dict dict, const char *p, void *client,
+                        int (*f)(const char *info, void *client));
 
-YAZ_EXPORT
-int dict_lookup_ec (Dict dict, char *p, int range, int (*f)(char *name));
 
+/** \brief lookup item(s) in dictionary with error correction
+    \param dict dictionary handle
+    \param p string-z with lookup string
+    \param range number of allowed errors(extra/substituted/missing char)
+    \param f function be called for each match
+    \retval 0 OK
+    \retval -1 error
+*/
 YAZ_EXPORT
-int dict_lookup_grep (Dict dict, const char *p, int range, void *client,
-		      int *max_pos, int init_pos,
-		      int (*f)(char *name, const char *info, void *client));
-
+int dict_lookup_ec(Dict dict, char *p, int range, int (*f)(char *name));
+
+/** \brief regular expression search with error correction
+    \param dict dictionary handle
+    \param p regular expression string-z
+    \param range number of allowed errors(extra/substituted/missing char)
+    \param client client data pointer to be passed to match function f
+    \param max_pos on return holds maximum number of chars that match (prefix)
+    \param init_pos number of leading non-error corrected chars.
+    \param f function be called for each match
+    \retval 0 OK
+    \retval 1 OK
+    \retval -1 error (such as bad regular expression)
+*/
+YAZ_EXPORT
+int dict_lookup_grep(Dict dict, const char *p, int range, void *client,
+                     int *max_pos, int init_pos,
+                     int (*f)(char *name, const char *info, void *client));
+
+/** \brief dictionary scan
+    \param dict dictionary handle
+    \param str start pint term (string-z)
+    \param before number of terms to be visited preceding str
+    \param after number of terms to be visited following str
+    \param client client data pointer to be passed to match function f
+    \param f function be called for each matching term
+    \retval 0 OK, and no terms visited
+    \retval 1 OK, and some terms have been visited
+    \retval -1 error
+*/
 YAZ_EXPORT
-int dict_scan (Dict dict, char *str, 
-	       int *before, int *after, void *client,
-	       int (*f)(char *name, const char *info, int pos, void *client));
+int dict_scan(Dict dict, char *str, 
+              int *before, int *after, void *client,
+              int (*f)(char *name, const char *info, int pos, void *client));
 
+
+/** \brief install character mapping handler for dict_lookup_grep
+    \param dict dictionary handle
+    \param vp client data to be passed to cmap function handler
+    \param cmap function be called for each character
+    
+    This function must be called prior to using dict_grep_lookup.
+    If vp is NULL, no character mapping takes place for dict_lookup_grep.
+*/
 YAZ_EXPORT 
-void dict_grep_cmap (Dict dict, void *vp,
-		     const char **(*cmap)(void *vp,
-					  const char **from, int len));
+void dict_grep_cmap(Dict dict, void *vp,
+                    const char **(*cmap)(void *vp,
+                                         const char **from, int len));
 
 YAZ_EXPORT
-int dict_copy_compact (BFiles bfs, const char *from, const char *to);
+int dict_copy_compact(BFiles bfs, const char *from, const char *to);
 
 YAZ_END_CDECL
    
@@ -95,4 +181,3 @@ YAZ_END_CDECL
  * End:
  * vim: shiftwidth=4 tabstop=8 expandtab
  */
-