Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_hash.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_hash.h
24  * @brief Dumping and reading hash tables to/from files.
25  */
26 
27 
28 #ifndef SVN_HASH_H
29 #define SVN_HASH_H
30 
31 #include <apr.h>
32 #include <apr_pools.h>
33 #include <apr_hash.h>
34 #include <apr_tables.h>
35 #include <apr_file_io.h> /* for apr_file_t */
36 
37 #include "svn_types.h"
38 #include "svn_io.h" /* for svn_stream_t */
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif /* __cplusplus */
43 
44 
45 /** The longest the "K <number>" line can be in one of our hashdump files. */
46 #define SVN_KEYLINE_MAXLEN 100
47 
48 /**
49  * @defgroup svn_hash_support Hash table serialization support
50  * @{
51  */
52 
53 /*----------------------------------------------------*/
54 
55 /** Reading/writing hashtables to disk
56  *
57  * @defgroup svn_hash_read_write Reading and writing hashtables to disk
58  * @{
59  */
60 
61 /**
62  * The conventional terminator for hash dumps.
63  *
64  * @since New in 1.1.
65  */
66 #define SVN_HASH_TERMINATOR "END"
67 
68 /**
69  * Read a hash table from @a stream, storing the resultants names and
70  * values in @a hash. Use a @a pool for all allocations. @a hash will
71  * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values.
72  * If @a terminator is NULL, expect the hash to be terminated by the
73  * end of the stream; otherwise, expect the hash to be terminated by a
74  * line containing @a terminator. Pass @c SVN_HASH_TERMINATOR to use
75  * the conventional terminator "END".
76  *
77  * @since New in 1.1.
78  */
80 svn_hash_read2(apr_hash_t *hash,
81  svn_stream_t *stream,
82  const char *terminator,
83  apr_pool_t *pool);
84 
85 /**
86  * Dump @a hash to @a stream. Use @a pool for all allocations. @a
87  * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt>
88  * values. If @a terminator is not NULL, terminate the hash with a
89  * line containing @a terminator.
90  *
91  * @since New in 1.1.
92  */
94 svn_hash_write2(apr_hash_t *hash,
95  svn_stream_t *stream,
96  const char *terminator,
97  apr_pool_t *pool);
98 
99 /**
100  * Similar to svn_hash_read2(), but allows @a stream to contain
101  * deletion lines which remove entries from @a hash as well as adding
102  * to it.
103  *
104  * @since New in 1.1.
105  */
106 svn_error_t *
107 svn_hash_read_incremental(apr_hash_t *hash,
108  svn_stream_t *stream,
109  const char *terminator,
110  apr_pool_t *pool);
111 
112 /**
113  * Similar to svn_hash_write2(), but only writes out entries for
114  * keys which differ between @a hash and @a oldhash, and also writes
115  * out deletion lines for keys which are present in @a oldhash but not
116  * in @a hash.
117  *
118  * @since New in 1.1.
119  */
120 svn_error_t *
121 svn_hash_write_incremental(apr_hash_t *hash,
122  apr_hash_t *oldhash,
123  svn_stream_t *stream,
124  const char *terminator,
125  apr_pool_t *pool);
126 
127 /**
128  * This function behaves like svn_hash_read2(), but it only works
129  * on an apr_file_t input, empty files are accepted, and the hash is
130  * expected to be terminated with a line containing "END" or
131  * "PROPS-END".
132  *
133  * @deprecated Provided for backward compatibility with the 1.0 API.
134  */
136 svn_error_t *
137 svn_hash_read(apr_hash_t *hash,
138  apr_file_t *srcfile,
139  apr_pool_t *pool);
140 
141 /**
142  * This function behaves like svn_hash_write2(), but it only works
143  * on an apr_file_t output, and the terminator is always "END".
144  *
145  * @deprecated Provided for backward compatibility with the 1.0 API.
146  */
148 svn_error_t *
149 svn_hash_write(apr_hash_t *hash,
150  apr_file_t *destfile,
151  apr_pool_t *pool);
152 
153 /** @} */
154 
155 
156 /** Taking the "diff" of two hash tables.
157  *
158  * @defgroup svn_hash_diff Taking the diff of two hash tables.
159  * @{
160  */
161 
162 /** Hash key status indicator for svn_hash_diff_func_t. */
164  {
165  /* Key is present in both hashes. */
166  svn_hash_diff_key_both,
167 
168  /* Key is present in first hash only. */
169  svn_hash_diff_key_a,
170 
171  /* Key is present in second hash only. */
172  svn_hash_diff_key_b
173  };
174 
175 
176 /** Function type for expressing a key's status between two hash tables. */
177 typedef svn_error_t *(*svn_hash_diff_func_t)
178  (const void *key, apr_ssize_t klen,
179  enum svn_hash_diff_key_status status,
180  void *baton);
181 
182 
183 /** Take the diff of two hashtables.
184  *
185  * For each key in the union of @a hash_a's and @a hash_b's keys, invoke
186  * @a diff_func exactly once, passing the key, the key's length, an enum
187  * @c svn_hash_diff_key_status indicating which table(s) the key appears
188  * in, and @a diff_func_baton.
189  *
190  * Process all keys of @a hash_a first, then all remaining keys of @a hash_b.
191  *
192  * If @a diff_func returns error, return that error immediately, without
193  * applying @a diff_func to anything else.
194  *
195  * @a hash_a or @a hash_b or both may be NULL; treat a null table as though
196  * empty.
197  *
198  * Use @a pool for temporary allocation.
199  */
200 svn_error_t *
201 svn_hash_diff(apr_hash_t *hash_a,
202  apr_hash_t *hash_b,
203  svn_hash_diff_func_t diff_func,
204  void *diff_func_baton,
205  apr_pool_t *pool);
206 
207 /** @} */
208 
209 
210 /**
211  * @defgroup svn_hash_misc Miscellaneous hash APIs
212  * @{
213  */
214 
215 /**
216  * Return the keys to @a hash in @a *array. The keys are assumed to be
217  * (const char *). The keys are in no particular order.
218  *
219  * @a *array itself is allocated in @a pool; however, the keys are not
220  * copied from the hash.
221  *
222  * @since New in 1.5.
223  */
224 svn_error_t *
225 svn_hash_keys(apr_array_header_t **array,
226  apr_hash_t *hash,
227  apr_pool_t *pool);
228 
229 /**
230  * Set @a *hash to a new hash whose keys come from the items in @a keys
231  * (an array of <tt>const char *</tt> items), and whose values are
232  * match their corresponding key. Use @a pool for all allocations
233  * (including @a *hash, its keys, and its values).
234  *
235  * @since New in 1.5.
236  */
237 svn_error_t *
238 svn_hash_from_cstring_keys(apr_hash_t **hash,
239  const apr_array_header_t *keys,
240  apr_pool_t *pool);
241 
242 /* For the Subversion developers, this #define makes the svn_hash_gets and
243  * svn_hash_sets macros forward their parameters through functions in order to
244  * gain type checking for the 'key' parameter which the basic apr_hash_* APIs
245  * declare only as 'void *'.
246  */
247 #ifdef SVN_DEBUG
248 #define SVN_HASH__GETS_SETS
249 #endif
250 
251 #ifdef SVN_HASH__GETS_SETS
252 void *
253 svn_hash__gets(apr_hash_t *ht, const char *key);
254 
255 #define svn_hash_gets(ht, key) \
256  svn_hash__gets(ht, key)
257 #else
258 /** Shortcut for apr_hash_get() with a const char * key.
259  *
260  * @since New in 1.8.
261  */
262 #define svn_hash_gets(ht, key) \
263  apr_hash_get(ht, key, APR_HASH_KEY_STRING)
264 #endif
265 
266 #ifdef SVN_HASH__GETS_SETS
267 void
268 svn_hash__sets(apr_hash_t *ht, const char *key, const void *value);
269 
270 #define svn_hash_sets(ht, key, val) \
271  svn_hash__sets(ht, key, val)
272 #else
273 /** Shortcut for apr_hash_set() with a const char * key.
274  *
275  * @since New in 1.8.
276  */
277 #define svn_hash_sets(ht, key, val) \
278  apr_hash_set(ht, key, APR_HASH_KEY_STRING, val)
279 #endif
280 
281 /** @} */
282 
283 /** @} */
284 
285 #ifdef __cplusplus
286 }
287 #endif /* __cplusplus */
288 
289 #endif /* SVN_HASH_H */