include/idzebra/dict.h

   1 /* $Id: dict.h,v 1.8 2006-08-29 11:28:44 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 YAZ_EXPORT
 109 int dict_delete_subtree(Dict dict, const char *p, void *client,
 110                         int (*f)(const char *info, void *client));
 111
 112
 113 /** \brief lookup item(s) in dictionary with error correction
 114     \param dict dictionary handle
 115     \param p string-z with lookup string
 116     \param range number of allowed errors(extra/substituted/missing char)
 117     \param f function be called for each match
 118     \retval 0 OK
 119     \retval -1 error
 120 */
 121 YAZ_EXPORT
 122 int dict_lookup_ec(Dict dict, char *p, int range, int (*f)(char *name));
 123
 124 /** \brief regular expression search with error correction
 125     \param dict dictionary handle
 126     \param p regular expression string-z
 127     \param range number of allowed errors(extra/substituted/missing char)
 128     \param client client data pointer to be passed to match function f
 129     \param max_pos on return holds maximum number of chars that match (prefix)
 130     \param init_pos number of leading non-error corrected chars.
 131     \param f function be called for each match
 132     \retval 0 OK
 133     \retval 1 OK
 134     \retval -1 error (such as bad regular expression)
 135 */
 136 YAZ_EXPORT
 137 int dict_lookup_grep(Dict dict, const char *p, int range, void *client,
 138                      int *max_pos, int init_pos,
 139                      int (*f)(char *name, const char *info, void *client));
 140
 141 /** \brief dictionary scan
 142     \param dict dictionary handle
 143     \param str start pint term (string-z)
 144     \param before number of terms to be visited preceding str
 145     \param after number of terms to be visited following str
 146     \param client client data pointer to be passed to match function f
 147     \param f function be called for each matching term
 148     \retval 0 OK, and no terms visited
 149     \retval 1 OK, and some terms have been visited
 150     \retval -1 error
 151 */
 152 YAZ_EXPORT
 153 int dict_scan(Dict dict, char *str,
 154               int *before, int *after, void *client,
 155               int (*f)(char *name, const char *info, int pos, void *client));
 156
 157
 158 /** \brief install character mapping handler for dict_lookup_grep
 159     \param dict dictionary handle
 160     \param vp client data to be passed to cmap function handler
 161     \param cmap function be called for each character
 162
 163     This function must be called prior to using dict_grep_lookup.
 164     If vp is NULL, no character mapping takes place for dict_lookup_grep.
 165 */
 166 YAZ_EXPORT
 167 void dict_grep_cmap(Dict dict, void *vp,
 168                     const char **(*cmap)(void *vp,
 169                                          const char **from, int len));
 170
 171 YAZ_EXPORT
 172 int dict_copy_compact(BFiles bfs, const char *from, const char *to);
 173
 174 YAZ_END_CDECL
 175
 176 #endif
 177 /*
 178  * Local variables:
 179  * c-basic-offset: 4
 180  * indent-tabs-mode: nil
 181  * End:
 182  * vim: shiftwidth=4 tabstop=8 expandtab
 183  */