1 /* $Id: dict.h,v 1.13 2006-12-12 13:42:23 adam Exp $
2 Copyright (C) 1995-2006
5 This file is part of the Zebra server.
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
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
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
24 \brief Zebra dictionary
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.
34 #include <yaz/yconfig.h>
35 #include <idzebra/bfile.h>
40 * \brief Dictionary handle
42 * Most dictionary functions operatate on a Dict type (object).
44 typedef struct Dict_struct *Dict;
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
56 Dict dict_open(BFiles bfs, const char *name, int cache, int rw,
57 int compact_flag, int page_size);
59 /** \brief closes dictionary
65 int dict_close(Dict dict);
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)
78 int dict_insert(Dict dict, const char *p, int userlen, void *userinfo);
80 /** \brief deletes item from dictionary
81 \param dict dictionary handle
82 \param p string-z with lookup string
84 \retval 1 p found and deleted
88 int dict_delete(Dict dict, const char *p);
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
97 char *dict_lookup(Dict dict, const char *p);
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)
108 Function f is called for each item to be deleted.
111 int dict_delete_subtree(Dict dict, const char *p, void *client,
112 int (*f)(const char *info, void *client));
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)
123 Function f is called for each item matched.
126 int dict_lookup_ec(Dict dict, char *p, int range, int (*f)(char *name));
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)
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.
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));
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
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.
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));
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
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.
178 void dict_grep_cmap(Dict dict, void *vp,
179 const char **(*cmap)(void *vp,
180 const char **from, int len));
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
188 int dict_copy_compact(BFiles bfs, const char *from, const char *to);
190 /** \brief reset Dictionary (makes it empty)
191 \param dict dictionary handle
194 void dict_clean(Dict dict);
196 /** \brief get number of lookup operations, since dict_open
197 \param dict dictionary handle
198 \returns number of operatons
201 zint dict_get_no_lookup(Dict dict);
203 /** \brief get number of insert operations, since dict_open
204 \param dict dictionary handle
205 \returns number of operatons
208 zint dict_get_no_insert(Dict dict);
210 /** \brief get number of page split operations, since dict_open
211 \param dict dictionary handle
212 \returns number of operatons
215 zint dict_get_no_split(Dict dict);
223 * indent-tabs-mode: nil
225 * vim: shiftwidth=4 tabstop=8 expandtab