Happy new year.
[idzebra-moved-to-github.git] / 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