include/idzebra/dict.h

   1 /* This file is part of the Zebra server.
   2    Copyright (C) 1994-2011 Index Data
   3
   4 Zebra is free software; you can redistribute it and/or modify it under
   5 the terms of the GNU General Public License as published by the Free
   6 Software Foundation; either version 2, or (at your option) any later
   7 version.
   8
   9 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
  10 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12 for more details.
  13
  14 You should have received a copy of the GNU General Public License
  15 along with this program; if not, write to the Free Software
  16 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  17
  18 */
  19
  20 /** \file dict.h
  21     \brief Zebra dictionary
  22
  23     The dictionary is a hash that maps a string to a value.
  24     The value is opaque and is defined as a sequence of bytes
  25     with a length in the range 0 to 255.
  26 */
  27
  28 #ifndef DICT_H
  29 #define DICT_H
  30
  31 #include <yaz/yconfig.h>
  32 #include <idzebra/bfile.h>
  33
  34 YAZ_BEGIN_CDECL
  35
  36 /** \var Dict
  37  * \brief Dictionary handle
  38  *
  39  * Most dictionary functions operatate on a Dict type (object).
  40  */
  41 typedef struct Dict_struct *Dict;
  42
  43 /** \brief open dictionary
  44     \param bfs block file storage
  45     \param name name of dictionary file
  46     \param cache number of pages to cache
  47     \param rw 0=read-only, 1=read&write
  48     \param compact_flag 1=write with compact, 0=normal paged operation
  49     \param page_size page size of disc block
  50     \returns dictionary handle
  51 */
  52 YAZ_EXPORT
  53 Dict dict_open(BFiles bfs, const char *name, int cache, int rw,
  54                int compact_flag, int page_size);
  55
  56 /** \brief closes dictionary
  57     \param dict handle
  58     \retval 0 OK
  59     \retval -1 failure
  60 */
  61 YAZ_EXPORT
  62 int dict_close(Dict dict);
  63
  64 /** \brief insert item into dictionary
  65     \param dict dictionary handle
  66     \param p string-z with lookup string
  67     \param userlen length of user data (associated with p)
  68     \param userinfo userdata (of size userlen)
  69     \retval 0 p is new and inserted OK
  70     \retval 1 p is updated (already exists) and userinfo is modified
  71     \retval 2 p already exists and userinfo is unmodified (same as before)
  72     \retval -1 error
  73 */
  74 YAZ_EXPORT
  75 int dict_insert(Dict dict, const char *p, int userlen, void *userinfo);
  76
  77 /** \brief deletes item from dictionary
  78     \param dict dictionary handle
  79     \param p string-z with lookup string
  80     \retval 0 p not found
  81     \retval 1 p found and deleted
  82     \retval -1 error
  83 */
  84 YAZ_EXPORT
  85 int dict_delete(Dict dict, const char *p);
  86
  87 /** \brief lookup item in dictionary
  88     \param dict dictionary handle
  89     \param p string-z with lookup string
  90     \retval NULL not found
  91     \retval value where value[0]=userlen, value[1..userlen] is userinfo data
  92 */
  93 YAZ_EXPORT
  94 char *dict_lookup(Dict dict, const char *p);
  95
  96 /** \brief delete items with a given prefix from dictionary
  97     \param dict dictionary handle
  98     \param p string-z with prefix
  99     \param client client data to be supplied to function f
 100     \param f function which gets called for each item in tree
 101     \retval 0 OK (0 or more entries deleted)
 102     \retval 1 OK (1 or more entries delete)
 103     \retval -1 ERROR
 104
 105     Function f is called for each item to be deleted.
 106 */
 107 YAZ_EXPORT
 108 int dict_delete_subtree(Dict dict, const char *p, void *client,
 109                         int (*f)(const char *info, void *client));
 110
 111
 112 /** \brief lookup item(s) in dictionary with error correction
 113     \param dict dictionary handle
 114     \param p string-z with lookup string
 115     \param range number of allowed errors(extra/substituted/missing char)
 116     \param f function be called for each match (NULL for no call of f)
 117     \retval 0 OK
 118     \retval -1 error
 119
 120     Function f is called for each item matched.
 121 */
 122 YAZ_EXPORT
 123 int dict_lookup_ec(Dict dict, char *p, int range, int (*f)(char *name));
 124
 125 /** \brief regular expression search with error correction
 126     \param dict dictionary handle
 127     \param p regular expression string-z
 128     \param range number of allowed errors(extra/substituted/missing char)
 129     \param client client data pointer to be passed to match function f
 130     \param max_pos on return holds maximum number of chars that match (prefix)
 131     \param init_pos number of leading non-error corrected chars.
 132     \param f function be called for each match
 133     \retval 0 Operation complete. Function f returned zero value always
 134     \retval >0 Operation incomplete. Function f returned a non-zero value
 135     \retval -1 error (such as bad regular expression)
 136
 137     The function f is called for each match. If function f returns
 138     non-zero value the grep operation is stopped and the returned
 139     non-zero value is also returned by dict_lookup_ec.
 140 */
 141 YAZ_EXPORT
 142 int dict_lookup_grep(Dict dict, const char *p, int range, void *client,
 143                      int *max_pos, int init_pos,
 144                      int (*f)(char *name, const char *info, void *client));
 145
 146 /** \brief dictionary scan
 147     \param dict dictionary handle
 148     \param str start pint term (string-z)
 149     \param before number of terms to be visited preceding str
 150     \param after number of terms to be visited following str
 151     \param client client data pointer to be passed to match function f
 152     \param f function be called for each matching term
 153     \retval 0 Successful
 154     \retval -1 error
 155
 156     If the callback function f returns 0 the scan operation visits
 157     all terms in range (before to after); if the function returns non-zero
 158     the scan operation is cancelled.
 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 /** \brief reset Dictionary (makes it empty)
 188     \param dict dictionary handle
 189 */
 190 YAZ_EXPORT
 191 void dict_clean(Dict dict);
 192
 193 /** \brief get number of lookup operations, since dict_open
 194     \param dict dictionary handle
 195     \returns number of operatons
 196 */
 197 YAZ_EXPORT
 198 zint dict_get_no_lookup(Dict dict);
 199
 200 /** \brief get number of insert operations, since dict_open
 201     \param dict dictionary handle
 202     \returns number of operatons
 203 */
 204 YAZ_EXPORT
 205 zint dict_get_no_insert(Dict dict);
 206
 207 /** \brief get number of page split operations, since dict_open
 208     \param dict dictionary handle
 209     \returns number of operatons
 210 */
 211 YAZ_EXPORT
 212 zint dict_get_no_split(Dict dict);
 213
 214 YAZ_END_CDECL
 215
 216 #endif
 217 /*
 218  * Local variables:
 219  * c-basic-offset: 4
 220  * c-file-style: "Stroustrup"
 221  * indent-tabs-mode: nil
 222  * End:
 223  * vim: shiftwidth=4 tabstop=8 expandtab
 224  */
 225