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 41251881Speter#ifdef __cplusplus 42251881Speterextern "C" { 43251881Speter#endif /* __cplusplus */ 44251881Speter 45251881Speter 46251881Speter/** The longest the "K <number>" line can be in one of our hashdump files. */ 47251881Speter#define SVN_KEYLINE_MAXLEN 100 48251881Speter 49251881Speter/** 50251881Speter * @defgroup svn_hash_support Hash table serialization support 51251881Speter * @{ 52251881Speter */ 53251881Speter 54251881Speter/*----------------------------------------------------*/ 55251881Speter 56251881Speter/** Reading/writing hashtables to disk 57251881Speter * 58251881Speter * @defgroup svn_hash_read_write Reading and writing hashtables to disk 59251881Speter * @{ 60251881Speter */ 61251881Speter 62251881Speter/** 63251881Speter * The conventional terminator for hash dumps. 64251881Speter * 65251881Speter * @since New in 1.1. 66251881Speter */ 67251881Speter#define SVN_HASH_TERMINATOR "END" 68251881Speter 69251881Speter/** 70251881Speter * Read a hash table from @a stream, storing the resultants names and 71251881Speter * values in @a hash. Use a @a pool for all allocations. @a hash will 72251881Speter * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values. 73251881Speter * If @a terminator is NULL, expect the hash to be terminated by the 74251881Speter * end of the stream; otherwise, expect the hash to be terminated by a 75251881Speter * line containing @a terminator. Pass @c SVN_HASH_TERMINATOR to use 76251881Speter * the conventional terminator "END". 77251881Speter * 78251881Speter * @since New in 1.1. 79251881Speter */ 80251881Spetersvn_error_t * 81251881Spetersvn_hash_read2(apr_hash_t *hash, 82251881Speter svn_stream_t *stream, 83251881Speter const char *terminator, 84251881Speter apr_pool_t *pool); 85251881Speter 86251881Speter/** 87251881Speter * Dump @a hash to @a stream. Use @a pool for all allocations. @a 88251881Speter * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt> 89251881Speter * values. If @a terminator is not NULL, terminate the hash with a 90251881Speter * line containing @a terminator. 91251881Speter * 92251881Speter * @since New in 1.1. 93251881Speter */ 94251881Spetersvn_error_t * 95251881Spetersvn_hash_write2(apr_hash_t *hash, 96251881Speter svn_stream_t *stream, 97251881Speter const char *terminator, 98251881Speter apr_pool_t *pool); 99251881Speter 100251881Speter/** 101251881Speter * Similar to svn_hash_read2(), but allows @a stream to contain 102251881Speter * deletion lines which remove entries from @a hash as well as adding 103251881Speter * to it. 104251881Speter * 105251881Speter * @since New in 1.1. 106251881Speter */ 107251881Spetersvn_error_t * 108251881Spetersvn_hash_read_incremental(apr_hash_t *hash, 109251881Speter svn_stream_t *stream, 110251881Speter const char *terminator, 111251881Speter apr_pool_t *pool); 112251881Speter 113251881Speter/** 114251881Speter * Similar to svn_hash_write2(), but only writes out entries for 115251881Speter * keys which differ between @a hash and @a oldhash, and also writes 116251881Speter * out deletion lines for keys which are present in @a oldhash but not 117251881Speter * in @a hash. 118251881Speter * 119251881Speter * @since New in 1.1. 120251881Speter */ 121251881Spetersvn_error_t * 122251881Spetersvn_hash_write_incremental(apr_hash_t *hash, 123251881Speter apr_hash_t *oldhash, 124251881Speter svn_stream_t *stream, 125251881Speter const char *terminator, 126251881Speter apr_pool_t *pool); 127251881Speter 128251881Speter/** 129251881Speter * This function behaves like svn_hash_read2(), but it only works 130251881Speter * on an apr_file_t input, empty files are accepted, and the hash is 131251881Speter * expected to be terminated with a line containing "END" or 132251881Speter * "PROPS-END". 133251881Speter * 134251881Speter * @deprecated Provided for backward compatibility with the 1.0 API. 135251881Speter */ 136251881SpeterSVN_DEPRECATED 137251881Spetersvn_error_t * 138251881Spetersvn_hash_read(apr_hash_t *hash, 139251881Speter apr_file_t *srcfile, 140251881Speter apr_pool_t *pool); 141251881Speter 142251881Speter/** 143251881Speter * This function behaves like svn_hash_write2(), but it only works 144251881Speter * on an apr_file_t output, and the terminator is always "END". 145251881Speter * 146251881Speter * @deprecated Provided for backward compatibility with the 1.0 API. 147251881Speter */ 148251881SpeterSVN_DEPRECATED 149251881Spetersvn_error_t * 150251881Spetersvn_hash_write(apr_hash_t *hash, 151251881Speter apr_file_t *destfile, 152251881Speter apr_pool_t *pool); 153251881Speter 154251881Speter/** @} */ 155251881Speter 156251881Speter 157251881Speter/** Taking the "diff" of two hash tables. 158251881Speter * 159251881Speter * @defgroup svn_hash_diff Taking the diff of two hash tables. 160251881Speter * @{ 161251881Speter */ 162251881Speter 163251881Speter/** Hash key status indicator for svn_hash_diff_func_t. */ 164251881Speterenum svn_hash_diff_key_status 165251881Speter { 166251881Speter /* Key is present in both hashes. */ 167251881Speter svn_hash_diff_key_both, 168251881Speter 169251881Speter /* Key is present in first hash only. */ 170251881Speter svn_hash_diff_key_a, 171251881Speter 172251881Speter /* Key is present in second hash only. */ 173251881Speter svn_hash_diff_key_b 174251881Speter }; 175251881Speter 176251881Speter 177251881Speter/** Function type for expressing a key's status between two hash tables. */ 178251881Spetertypedef svn_error_t *(*svn_hash_diff_func_t) 179251881Speter (const void *key, apr_ssize_t klen, 180251881Speter enum svn_hash_diff_key_status status, 181251881Speter void *baton); 182251881Speter 183251881Speter 184251881Speter/** Take the diff of two hashtables. 185251881Speter * 186251881Speter * For each key in the union of @a hash_a's and @a hash_b's keys, invoke 187251881Speter * @a diff_func exactly once, passing the key, the key's length, an enum 188251881Speter * @c svn_hash_diff_key_status indicating which table(s) the key appears 189251881Speter * in, and @a diff_func_baton. 190251881Speter * 191251881Speter * Process all keys of @a hash_a first, then all remaining keys of @a hash_b. 192251881Speter * 193251881Speter * If @a diff_func returns error, return that error immediately, without 194251881Speter * applying @a diff_func to anything else. 195251881Speter * 196251881Speter * @a hash_a or @a hash_b or both may be NULL; treat a null table as though 197251881Speter * empty. 198251881Speter * 199251881Speter * Use @a pool for temporary allocation. 200251881Speter */ 201251881Spetersvn_error_t * 202251881Spetersvn_hash_diff(apr_hash_t *hash_a, 203251881Speter apr_hash_t *hash_b, 204251881Speter svn_hash_diff_func_t diff_func, 205251881Speter void *diff_func_baton, 206251881Speter apr_pool_t *pool); 207251881Speter 208251881Speter/** @} */ 209251881Speter 210251881Speter 211251881Speter/** 212251881Speter * @defgroup svn_hash_misc Miscellaneous hash APIs 213251881Speter * @{ 214251881Speter */ 215251881Speter 216251881Speter/** 217251881Speter * Return the keys to @a hash in @a *array. The keys are assumed to be 218251881Speter * (const char *). The keys are in no particular order. 219251881Speter * 220251881Speter * @a *array itself is allocated in @a pool; however, the keys are not 221251881Speter * copied from the hash. 222251881Speter * 223251881Speter * @since New in 1.5. 224251881Speter */ 225251881Spetersvn_error_t * 226251881Spetersvn_hash_keys(apr_array_header_t **array, 227251881Speter apr_hash_t *hash, 228251881Speter apr_pool_t *pool); 229251881Speter 230251881Speter/** 231251881Speter * Set @a *hash to a new hash whose keys come from the items in @a keys 232251881Speter * (an array of <tt>const char *</tt> items), and whose values are 233251881Speter * match their corresponding key. Use @a pool for all allocations 234251881Speter * (including @a *hash, its keys, and its values). 235251881Speter * 236251881Speter * @since New in 1.5. 237251881Speter */ 238251881Spetersvn_error_t * 239251881Spetersvn_hash_from_cstring_keys(apr_hash_t **hash, 240251881Speter const apr_array_header_t *keys, 241251881Speter apr_pool_t *pool); 242251881Speter 243251881Speter/** Shortcut for apr_hash_get() with a const char * key. 244251881Speter * 245251881Speter * @since New in 1.8. 246251881Speter */ 247251881Speter#define svn_hash_gets(ht, key) \ 248251881Speter apr_hash_get(ht, key, APR_HASH_KEY_STRING) 249251881Speter 250251881Speter/** Shortcut for apr_hash_set() with a const char * key. 251251881Speter * 252251881Speter * @since New in 1.8. 253251881Speter */ 254251881Speter#define svn_hash_sets(ht, key, val) \ 255251881Speter apr_hash_set(ht, key, APR_HASH_KEY_STRING, val) 256251881Speter 257251881Speter/** @} */ 258251881Speter 259251881Speter/** @} */ 260251881Speter 261251881Speter#ifdef __cplusplus 262251881Speter} 263251881Speter#endif /* __cplusplus */ 264251881Speter 265251881Speter#endif /* SVN_HASH_H */ 266