include/idzebra/dict.h

   1 /* $Id: dict.h,v 1.13 2006-12-12 13:42:23 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. Function f returned zero value always
 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 Successful
 157     \retval -1 error
 158
 159     If the callback function f returns 0 the scan operation visits
 160     all terms in range (before to after); if the function returns non-zero
 161     the scan operation is cancelled.
 162 */
 163 YAZ_EXPORT
 164 int dict_scan(Dict dict, char *str,
 165               int *before, int *after, void *client,
 166               int (*f)(char *name, const char *info, int pos, void *client));
 167
 168
 169 /** \brief install character mapping handler for dict_lookup_grep
 170     \param dict dictionary handle
 171     \param vp client data to be passed to cmap function handler
 172     \param cmap function be called for each character
 173
 174     This function must be called prior to using dict_grep_lookup.
 175     If vp is NULL, no character mapping takes place for dict_lookup_grep.
 176 */
 177 YAZ_EXPORT
 178 void dict_grep_cmap(Dict dict, void *vp,
 179                     const char **(*cmap)(void *vp,
 180                                          const char **from, int len));
 181
 182 /** \brief copies one dictionary to another
 183     \param bfs block file handle
 184     \param from source dictionary file
 185     \param to destination dictionary file
 186 */
 187 YAZ_EXPORT
 188 int dict_copy_compact(BFiles bfs, const char *from, const char *to);
 189
 190 /** \brief reset Dictionary (makes it empty)
 191     \param dict dictionary handle
 192 */
 193 YAZ_EXPORT
 194 void dict_clean(Dict dict);
 195
 196 /** \brief get number of lookup operations, since dict_open
 197     \param dict dictionary handle
 198     \returns number of operatons
 199 */
 200 YAZ_EXPORT
 201 zint dict_get_no_lookup(Dict dict);
 202
 203 /** \brief get number of insert operations, since dict_open
 204     \param dict dictionary handle
 205     \returns number of operatons
 206 */
 207 YAZ_EXPORT
 208 zint dict_get_no_insert(Dict dict);
 209
 210 /** \brief get number of page split operations, since dict_open
 211     \param dict dictionary handle
 212     \returns number of operatons
 213 */
 214 YAZ_EXPORT
 215 zint dict_get_no_split(Dict dict);
 216
 217 YAZ_END_CDECL
 218
 219 #endif
 220 /*
 221  * Local variables:
 222  * c-basic-offset: 4
 223  * indent-tabs-mode: nil
 224  * End:
 225  * vim: shiftwidth=4 tabstop=8 expandtab
 226  */