1251881Speter/** 2251881Speter * @copyright 3251881Speter * ==================================================================== 4251881Speter * Licensed to the Apache Software Foundation (ASF) under one 5251881Speter * or more contributor license agreements. See the NOTICE file 6251881Speter * distributed with this work for additional information 7251881Speter * regarding copyright ownership. The ASF licenses this file 8251881Speter * to you under the Apache License, Version 2.0 (the 9251881Speter * "License"); you may not use this file except in compliance 10251881Speter * with the License. You may obtain a copy of the License at 11251881Speter * 12251881Speter * http://www.apache.org/licenses/LICENSE-2.0 13251881Speter * 14251881Speter * Unless required by applicable law or agreed to in writing, 15251881Speter * software distributed under the License is distributed on an 16251881Speter * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17251881Speter * KIND, either express or implied. See the License for the 18251881Speter * specific language governing permissions and limitations 19251881Speter * under the License. 20251881Speter * ==================================================================== 21251881Speter * @endcopyright 22251881Speter * 23251881Speter * @file svn_hash.h 24251881Speter * @brief Dumping and reading hash tables to/from files. 25251881Speter */ 26251881Speter 27251881Speter 28251881Speter#ifndef SVN_HASH_H 29251881Speter#define SVN_HASH_H 30251881Speter 31251881Speter#include <apr.h> 32251881Speter#include <apr_pools.h> 33251881Speter#include <apr_hash.h> 34251881Speter#include <apr_tables.h> 35251881Speter#include <apr_file_io.h> /* for apr_file_t */ 36251881Speter 37251881Speter#include "svn_types.h" 38251881Speter#include "svn_io.h" /* for svn_stream_t */ 39251881Speter 40251881Speter#ifdef __cplusplus 41251881Speterextern "C" { 42251881Speter#endif /* __cplusplus */ 43251881Speter 44251881Speter 45251881Speter/** The longest the "K <number>" line can be in one of our hashdump files. */ 46251881Speter#define SVN_KEYLINE_MAXLEN 100 47251881Speter 48251881Speter/** 49251881Speter * @defgroup svn_hash_support Hash table serialization support 50251881Speter * @{ 51251881Speter */ 52251881Speter 53251881Speter/*----------------------------------------------------*/ 54251881Speter 55251881Speter/** Reading/writing hashtables to disk 56251881Speter * 57251881Speter * @defgroup svn_hash_read_write Reading and writing hashtables to disk 58251881Speter * @{ 59251881Speter */ 60251881Speter 61251881Speter/** 62251881Speter * The conventional terminator for hash dumps. 63251881Speter * 64251881Speter * @since New in 1.1. 65251881Speter */ 66251881Speter#define SVN_HASH_TERMINATOR "END" 67251881Speter 68251881Speter/** 69251881Speter * Read a hash table from @a stream, storing the resultants names and 70251881Speter * values in @a hash. Use a @a pool for all allocations. @a hash will 71251881Speter * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values. 72251881Speter * If @a terminator is NULL, expect the hash to be terminated by the 73251881Speter * end of the stream; otherwise, expect the hash to be terminated by a 74251881Speter * line containing @a terminator. Pass @c SVN_HASH_TERMINATOR to use 75251881Speter * the conventional terminator "END". 76251881Speter * 77251881Speter * @since New in 1.1. 78251881Speter */ 79251881Spetersvn_error_t * 80251881Spetersvn_hash_read2(apr_hash_t *hash, 81251881Speter svn_stream_t *stream, 82251881Speter const char *terminator, 83251881Speter apr_pool_t *pool); 84251881Speter 85251881Speter/** 86251881Speter * Dump @a hash to @a stream. Use @a pool for all allocations. @a 87251881Speter * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt> 88251881Speter * values. If @a terminator is not NULL, terminate the hash with a 89251881Speter * line containing @a terminator. 90251881Speter * 91251881Speter * @since New in 1.1. 92251881Speter */ 93251881Spetersvn_error_t * 94251881Spetersvn_hash_write2(apr_hash_t *hash, 95251881Speter svn_stream_t *stream, 96251881Speter const char *terminator, 97251881Speter apr_pool_t *pool); 98251881Speter 99251881Speter/** 100251881Speter * Similar to svn_hash_read2(), but allows @a stream to contain 101251881Speter * deletion lines which remove entries from @a hash as well as adding 102251881Speter * to it. 103251881Speter * 104251881Speter * @since New in 1.1. 105251881Speter */ 106251881Spetersvn_error_t * 107251881Spetersvn_hash_read_incremental(apr_hash_t *hash, 108251881Speter svn_stream_t *stream, 109251881Speter const char *terminator, 110251881Speter apr_pool_t *pool); 111251881Speter 112251881Speter/** 113251881Speter * Similar to svn_hash_write2(), but only writes out entries for 114251881Speter * keys which differ between @a hash and @a oldhash, and also writes 115251881Speter * out deletion lines for keys which are present in @a oldhash but not 116251881Speter * in @a hash. 117251881Speter * 118251881Speter * @since New in 1.1. 119251881Speter */ 120251881Spetersvn_error_t * 121251881Spetersvn_hash_write_incremental(apr_hash_t *hash, 122251881Speter apr_hash_t *oldhash, 123251881Speter svn_stream_t *stream, 124251881Speter const char *terminator, 125251881Speter apr_pool_t *pool); 126251881Speter 127251881Speter/** 128251881Speter * This function behaves like svn_hash_read2(), but it only works 129251881Speter * on an apr_file_t input, empty files are accepted, and the hash is 130251881Speter * expected to be terminated with a line containing "END" or 131251881Speter * "PROPS-END". 132251881Speter * 133251881Speter * @deprecated Provided for backward compatibility with the 1.0 API. 134251881Speter */ 135251881SpeterSVN_DEPRECATED 136251881Spetersvn_error_t * 137251881Spetersvn_hash_read(apr_hash_t *hash, 138251881Speter apr_file_t *srcfile, 139251881Speter apr_pool_t *pool); 140251881Speter 141251881Speter/** 142251881Speter * This function behaves like svn_hash_write2(), but it only works 143251881Speter * on an apr_file_t output, and the terminator is always "END". 144251881Speter * 145251881Speter * @deprecated Provided for backward compatibility with the 1.0 API. 146251881Speter */ 147251881SpeterSVN_DEPRECATED 148251881Spetersvn_error_t * 149251881Spetersvn_hash_write(apr_hash_t *hash, 150251881Speter apr_file_t *destfile, 151251881Speter apr_pool_t *pool); 152251881Speter 153251881Speter/** @} */ 154251881Speter 155251881Speter 156251881Speter/** Taking the "diff" of two hash tables. 157251881Speter * 158251881Speter * @defgroup svn_hash_diff Taking the diff of two hash tables. 159251881Speter * @{ 160251881Speter */ 161251881Speter 162251881Speter/** Hash key status indicator for svn_hash_diff_func_t. */ 163251881Speterenum svn_hash_diff_key_status 164251881Speter { 165251881Speter /* Key is present in both hashes. */ 166251881Speter svn_hash_diff_key_both, 167251881Speter 168251881Speter /* Key is present in first hash only. */ 169251881Speter svn_hash_diff_key_a, 170251881Speter 171251881Speter /* Key is present in second hash only. */ 172251881Speter svn_hash_diff_key_b 173251881Speter }; 174251881Speter 175251881Speter 176251881Speter/** Function type for expressing a key's status between two hash tables. */ 177251881Spetertypedef svn_error_t *(*svn_hash_diff_func_t) 178251881Speter (const void *key, apr_ssize_t klen, 179251881Speter enum svn_hash_diff_key_status status, 180251881Speter void *baton); 181251881Speter 182251881Speter 183251881Speter/** Take the diff of two hashtables. 184251881Speter * 185251881Speter * For each key in the union of @a hash_a's and @a hash_b's keys, invoke 186251881Speter * @a diff_func exactly once, passing the key, the key's length, an enum 187251881Speter * @c svn_hash_diff_key_status indicating which table(s) the key appears 188251881Speter * in, and @a diff_func_baton. 189251881Speter * 190251881Speter * Process all keys of @a hash_a first, then all remaining keys of @a hash_b. 191251881Speter * 192251881Speter * If @a diff_func returns error, return that error immediately, without 193251881Speter * applying @a diff_func to anything else. 194251881Speter * 195251881Speter * @a hash_a or @a hash_b or both may be NULL; treat a null table as though 196251881Speter * empty. 197251881Speter * 198251881Speter * Use @a pool for temporary allocation. 199251881Speter */ 200251881Spetersvn_error_t * 201251881Spetersvn_hash_diff(apr_hash_t *hash_a, 202251881Speter apr_hash_t *hash_b, 203251881Speter svn_hash_diff_func_t diff_func, 204251881Speter void *diff_func_baton, 205251881Speter apr_pool_t *pool); 206251881Speter 207251881Speter/** @} */ 208251881Speter 209251881Speter 210251881Speter/** 211251881Speter * @defgroup svn_hash_misc Miscellaneous hash APIs 212251881Speter * @{ 213251881Speter */ 214251881Speter 215251881Speter/** 216251881Speter * Return the keys to @a hash in @a *array. The keys are assumed to be 217251881Speter * (const char *). The keys are in no particular order. 218251881Speter * 219251881Speter * @a *array itself is allocated in @a pool; however, the keys are not 220251881Speter * copied from the hash. 221251881Speter * 222251881Speter * @since New in 1.5. 223251881Speter */ 224251881Spetersvn_error_t * 225251881Spetersvn_hash_keys(apr_array_header_t **array, 226251881Speter apr_hash_t *hash, 227251881Speter apr_pool_t *pool); 228251881Speter 229251881Speter/** 230251881Speter * Set @a *hash to a new hash whose keys come from the items in @a keys 231251881Speter * (an array of <tt>const char *</tt> items), and whose values are 232251881Speter * match their corresponding key. Use @a pool for all allocations 233251881Speter * (including @a *hash, its keys, and its values). 234251881Speter * 235251881Speter * @since New in 1.5. 236251881Speter */ 237251881Spetersvn_error_t * 238251881Spetersvn_hash_from_cstring_keys(apr_hash_t **hash, 239251881Speter const apr_array_header_t *keys, 240251881Speter apr_pool_t *pool); 241251881Speter 242362181Sdim/* For the Subversion developers, this #define makes the svn_hash_gets and 243362181Sdim * svn_hash_sets macros forward their parameters through functions in order to 244362181Sdim * gain type checking for the 'key' parameter which the basic apr_hash_* APIs 245362181Sdim * declare only as 'void *'. 246362181Sdim */ 247362181Sdim#ifdef SVN_DEBUG 248362181Sdim#define SVN_HASH__GETS_SETS 249362181Sdim#endif 250362181Sdim 251362181Sdim#ifdef SVN_HASH__GETS_SETS 252362181Sdimvoid * 253362181Sdimsvn_hash__gets_debug(apr_hash_t *ht, const char *key); 254362181Sdim 255362181Sdim#define svn_hash_gets(ht, key) \ 256362181Sdim svn_hash__gets_debug(ht, key) 257362181Sdim#else 258251881Speter/** Shortcut for apr_hash_get() with a const char * key. 259251881Speter * 260251881Speter * @since New in 1.8. 261251881Speter */ 262251881Speter#define svn_hash_gets(ht, key) \ 263251881Speter apr_hash_get(ht, key, APR_HASH_KEY_STRING) 264362181Sdim#endif 265251881Speter 266362181Sdim#ifdef SVN_HASH__GETS_SETS 267362181Sdimvoid 268362181Sdimsvn_hash__sets_debug(apr_hash_t *ht, const char *key, const void *value); 269362181Sdim 270362181Sdim#define svn_hash_sets(ht, key, val) \ 271362181Sdim svn_hash__sets_debug(ht, key, val) 272362181Sdim#else 273251881Speter/** Shortcut for apr_hash_set() with a const char * key. 274251881Speter * 275251881Speter * @since New in 1.8. 276251881Speter */ 277251881Speter#define svn_hash_sets(ht, key, val) \ 278251881Speter apr_hash_set(ht, key, APR_HASH_KEY_STRING, val) 279362181Sdim#endif 280251881Speter 281251881Speter/** @} */ 282251881Speter 283251881Speter/** @} */ 284251881Speter 285251881Speter#ifdef __cplusplus 286251881Speter} 287251881Speter#endif /* __cplusplus */ 288251881Speter 289251881Speter#endif /* SVN_HASH_H */ 290