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 41#ifdef __cplusplus 42extern "C" { 43#endif /* __cplusplus */ 44 45 46/** The longest the "K <number>" line can be in one of our hashdump files. */ 47#define SVN_KEYLINE_MAXLEN 100 48 49/** 50 * @defgroup svn_hash_support Hash table serialization support 51 * @{ 52 */ 53 54/*----------------------------------------------------*/ 55 56/** Reading/writing hashtables to disk 57 * 58 * @defgroup svn_hash_read_write Reading and writing hashtables to disk 59 * @{ 60 */ 61 62/** 63 * The conventional terminator for hash dumps. 64 * 65 * @since New in 1.1. 66 */ 67#define SVN_HASH_TERMINATOR "END" 68 69/** 70 * Read a hash table from @a stream, storing the resultants names and 71 * values in @a hash. Use a @a pool for all allocations. @a hash will 72 * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values. 73 * If @a terminator is NULL, expect the hash to be terminated by the 74 * end of the stream; otherwise, expect the hash to be terminated by a 75 * line containing @a terminator. Pass @c SVN_HASH_TERMINATOR to use 76 * the conventional terminator "END". 77 * 78 * @since New in 1.1. 79 */ 80svn_error_t * 81svn_hash_read2(apr_hash_t *hash, 82 svn_stream_t *stream, 83 const char *terminator, 84 apr_pool_t *pool); 85 86/** 87 * Dump @a hash to @a stream. Use @a pool for all allocations. @a 88 * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt> 89 * values. If @a terminator is not NULL, terminate the hash with a 90 * line containing @a terminator. 91 * 92 * @since New in 1.1. 93 */ 94svn_error_t * 95svn_hash_write2(apr_hash_t *hash, 96 svn_stream_t *stream, 97 const char *terminator, 98 apr_pool_t *pool); 99 100/** 101 * Similar to svn_hash_read2(), but allows @a stream to contain 102 * deletion lines which remove entries from @a hash as well as adding 103 * to it. 104 * 105 * @since New in 1.1. 106 */ 107svn_error_t * 108svn_hash_read_incremental(apr_hash_t *hash, 109 svn_stream_t *stream, 110 const char *terminator, 111 apr_pool_t *pool); 112 113/** 114 * Similar to svn_hash_write2(), but only writes out entries for 115 * keys which differ between @a hash and @a oldhash, and also writes 116 * out deletion lines for keys which are present in @a oldhash but not 117 * in @a hash. 118 * 119 * @since New in 1.1. 120 */ 121svn_error_t * 122svn_hash_write_incremental(apr_hash_t *hash, 123 apr_hash_t *oldhash, 124 svn_stream_t *stream, 125 const char *terminator, 126 apr_pool_t *pool); 127 128/** 129 * This function behaves like svn_hash_read2(), but it only works 130 * on an apr_file_t input, empty files are accepted, and the hash is 131 * expected to be terminated with a line containing "END" or 132 * "PROPS-END". 133 * 134 * @deprecated Provided for backward compatibility with the 1.0 API. 135 */ 136SVN_DEPRECATED 137svn_error_t * 138svn_hash_read(apr_hash_t *hash, 139 apr_file_t *srcfile, 140 apr_pool_t *pool); 141 142/** 143 * This function behaves like svn_hash_write2(), but it only works 144 * on an apr_file_t output, and the terminator is always "END". 145 * 146 * @deprecated Provided for backward compatibility with the 1.0 API. 147 */ 148SVN_DEPRECATED 149svn_error_t * 150svn_hash_write(apr_hash_t *hash, 151 apr_file_t *destfile, 152 apr_pool_t *pool); 153 154/** @} */ 155 156 157/** Taking the "diff" of two hash tables. 158 * 159 * @defgroup svn_hash_diff Taking the diff of two hash tables. 160 * @{ 161 */ 162 163/** Hash key status indicator for svn_hash_diff_func_t. */ 164enum svn_hash_diff_key_status 165 { 166 /* Key is present in both hashes. */ 167 svn_hash_diff_key_both, 168 169 /* Key is present in first hash only. */ 170 svn_hash_diff_key_a, 171 172 /* Key is present in second hash only. */ 173 svn_hash_diff_key_b 174 }; 175 176 177/** Function type for expressing a key's status between two hash tables. */ 178typedef svn_error_t *(*svn_hash_diff_func_t) 179 (const void *key, apr_ssize_t klen, 180 enum svn_hash_diff_key_status status, 181 void *baton); 182 183 184/** Take the diff of two hashtables. 185 * 186 * For each key in the union of @a hash_a's and @a hash_b's keys, invoke 187 * @a diff_func exactly once, passing the key, the key's length, an enum 188 * @c svn_hash_diff_key_status indicating which table(s) the key appears 189 * in, and @a diff_func_baton. 190 * 191 * Process all keys of @a hash_a first, then all remaining keys of @a hash_b. 192 * 193 * If @a diff_func returns error, return that error immediately, without 194 * applying @a diff_func to anything else. 195 * 196 * @a hash_a or @a hash_b or both may be NULL; treat a null table as though 197 * empty. 198 * 199 * Use @a pool for temporary allocation. 200 */ 201svn_error_t * 202svn_hash_diff(apr_hash_t *hash_a, 203 apr_hash_t *hash_b, 204 svn_hash_diff_func_t diff_func, 205 void *diff_func_baton, 206 apr_pool_t *pool); 207 208/** @} */ 209 210 211/** 212 * @defgroup svn_hash_misc Miscellaneous hash APIs 213 * @{ 214 */ 215 216/** 217 * Return the keys to @a hash in @a *array. The keys are assumed to be 218 * (const char *). The keys are in no particular order. 219 * 220 * @a *array itself is allocated in @a pool; however, the keys are not 221 * copied from the hash. 222 * 223 * @since New in 1.5. 224 */ 225svn_error_t * 226svn_hash_keys(apr_array_header_t **array, 227 apr_hash_t *hash, 228 apr_pool_t *pool); 229 230/** 231 * Set @a *hash to a new hash whose keys come from the items in @a keys 232 * (an array of <tt>const char *</tt> items), and whose values are 233 * match their corresponding key. Use @a pool for all allocations 234 * (including @a *hash, its keys, and its values). 235 * 236 * @since New in 1.5. 237 */ 238svn_error_t * 239svn_hash_from_cstring_keys(apr_hash_t **hash, 240 const apr_array_header_t *keys, 241 apr_pool_t *pool); 242 243/** Shortcut for apr_hash_get() with a const char * key. 244 * 245 * @since New in 1.8. 246 */ 247#define svn_hash_gets(ht, key) \ 248 apr_hash_get(ht, key, APR_HASH_KEY_STRING) 249 250/** Shortcut for apr_hash_set() with a const char * key. 251 * 252 * @since New in 1.8. 253 */ 254#define svn_hash_sets(ht, key, val) \ 255 apr_hash_set(ht, key, APR_HASH_KEY_STRING, val) 256 257/** @} */ 258 259/** @} */ 260 261#ifdef __cplusplus 262} 263#endif /* __cplusplus */ 264 265#endif /* SVN_HASH_H */ 266