include/idzebra/dict.h

   1 /* $Id: dict.h,v 1.9 2006-08-29 13:36:26 adam Exp $
   2    Copyright (C) 1995-2006
   3    Index Data ApS
   4
   5 This file is part of the Zebra server.
   6
   7 Zebra is free software; you can redistribute it and/or modify it under
   8 the terms of the GNU General Public License as published by the Free
   9 Software Foundation; either version 2, or (at your option) any later
  10 version.
  11
  12 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
  13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with this program; if not, write to the Free Software
  19 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20
  21 */
  22
  23 /** \file dict.h
  24     \brief Zebra dictionary
  25
  26     The dictionary is a hash that maps a string to a value.
  27     The value is opaque and is defined as a sequence of bytes
  28     with a length in the range 0 to 255.
  29 */
  30
  31 #ifndef DICT_H
  32 #define DICT_H
  33
  34 #include <yaz/yconfig.h>
  35 #include <idzebra/bfile.h>
  36
  37 YAZ_BEGIN_CDECL
  38
  39 /** \var Dict
  40  * \brief Dictionary handle
  41  *
  42  * Most dictionary functions operatate on a Dict type (object).
  43  */
  44 typedef struct Dict_struct *Dict;
  45
  46 /** \brief open dictionary
  47     \param bfs block file storage
  48     \param name name of dictionary file
  49     \param cache number of pages to cache
  50     \param rw 0=read-only, 1=read&write
  51     \param compact_flag 1=write with compact, 0=normal paged operation
  52     \param page_size page size of disc block
  53     \returns dictionary handle
  54 */
  55 YAZ_EXPORT
  56 Dict dict_open(BFiles bfs, const char *name, int cache, int rw,
  57                int compact_flag, int page_size);
  58
  59 /** \brief closes dictionary
  60     \param dict handle
  61     \retval 0 OK
  62     \retval -1 failure
  63 */
  64 YAZ_EXPORT
  65 int dict_close(Dict dict);
  66
  67 /** \brief insert item into dictionary
  68     \param dict dictionary handle
  69     \param p string-z with lookup string
  70     \param userlen length of user data (associated with p)
  71     \param userinfo userdata (of size userlen)
  72     \retval 0 p is new and inserted OK
  73     \retval 1 p is updated (already exists) and userinfo is modified
  74     \retval 2 p already exists and userinfo is unmodified (same as before)
  75     \retval -1 error
  76 */
  77 YAZ_EXPORT
  78 int dict_insert(Dict dict, const char *p, int userlen, void *userinfo);
  79
  80 /** \brief deletes item from dictionary
  81     \param dict dictionary handle
  82     \param p string-z with lookup string
  83     \retval 0 p not found
  84     \retval 1 p found and deleted
  85     \retval -1 error
  86 */
  87 YAZ_EXPORT
  88 int dict_delete(Dict dict, const char *p);
  89
  90 /** \brief lookup item in dictionary
  91     \param dict dictionary handle
  92     \param p string-z with lookup string
  93     \retval NULL not found
  94     \retval value where value[0]=userlen, value[1..userlen] is userinfo data
  95 */
  96 YAZ_EXPORT
  97 char *dict_lookup(Dict dict, const char *p);
  98
  99 /** \brief delete items with a given prefix from dictionary
 100     \param dict dictionary handle
 101     \param p string-z with prefix
 102     \param client client data to be supplied to function f
 103     \param f function which gets called for each item in tree
 104     \retval 0 OK (0 or more entries deleted)
 105     \retval 1 OK (1 or more entries delete)
 106     \retval -1 ERROR
 107
 108     Function f is called for each item to be deleted.
 109 */
 110 YAZ_EXPORT
 111 int dict_delete_subtree(Dict dict, const char *p, void *client,
 112                         int (*f)(const char *info, void *client));
 113
 114
 115 /** \brief lookup item(s) in dictionary with error correction
 116     \param dict dictionary handle
 117     \param p string-z with lookup string
 118     \param range number of allowed errors(extra/substituted/missing char)
 119     \param f function be called for each match (NULL for no call of f)
 120     \retval 0 OK
 121     \retval -1 error
 122
 123     Function f is called for each item matched.
 124 */
 125 YAZ_EXPORT
 126 int dict_lookup_ec(Dict dict, char *p, int range, int (*f)(char *name));
 127
 128 /** \brief regular expression search with error correction
 129     \param dict dictionary handle
 130     \param p regular expression string-z
 131     \param range number of allowed errors(extra/substituted/missing char)
 132     \param client client data pointer to be passed to match function f
 133     \param max_pos on return holds maximum number of chars that match (prefix)
 134     \param init_pos number of leading non-error corrected chars.
 135     \param f function be called for each match
 136     \retval 0 Operation complete.
 137     \retval >0 Operation incomplete. Function f returned a non-zero value
 138     \retval -1 error (such as bad regular expression)
 139
 140     The function f is called for each match. If function f returns
 141     non-zero value the grep operation is stopped and the returned
 142     non-zero value is also returned by dict_lookup_ec.
 143 */
 144 YAZ_EXPORT
 145 int dict_lookup_grep(Dict dict, const char *p, int range, void *client,
 146                      int *max_pos, int init_pos,
 147                      int (*f)(char *name, const char *info, void *client));
 148
 149 /** \brief dictionary scan
 150     \param dict dictionary handle
 151     \param str start pint term (string-z)
 152     \param before number of terms to be visited preceding str
 153     \param after number of terms to be visited following str
 154     \param client client data pointer to be passed to match function f
 155     \param f function be called for each matching term
 156     \retval 0 OK, and no terms visited
 157     \retval 1 OK, and some terms have been visited
 158     \retval -1 error
 159 */
 160 YAZ_EXPORT
 161 int dict_scan(Dict dict, char *str,
 162               int *before, int *after, void *client,
 163               int (*f)(char *name, const char *info, int pos, void *client));
 164
 165
 166 /** \brief install character mapping handler for dict_lookup_grep
 167     \param dict dictionary handle
 168     \param vp client data to be passed to cmap function handler
 169     \param cmap function be called for each character
 170
 171     This function must be called prior to using dict_grep_lookup.
 172     If vp is NULL, no character mapping takes place for dict_lookup_grep.
 173 */
 174 YAZ_EXPORT
 175 void dict_grep_cmap(Dict dict, void *vp,
 176                     const char **(*cmap)(void *vp,
 177                                          const char **from, int len));
 178
 179 /** \brief copies one dictionary to another
 180     \param bfs block file handle
 181     \param from source dictionary file
 182     \param to destination dictionary file
 183 */
 184 YAZ_EXPORT
 185 int dict_copy_compact(BFiles bfs, const char *from, const char *to);
 186
 187 YAZ_END_CDECL
 188
 189 #endif
 190 /*
 191  * Local variables:
 192  * c-basic-offset: 4
 193  * indent-tabs-mode: nil
 194  * End:
 195  * vim: shiftwidth=4 tabstop=8 expandtab
 196  */