Subversion
|
00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Licensed to the Apache Software Foundation (ASF) under one 00005 * or more contributor license agreements. See the NOTICE file 00006 * distributed with this work for additional information 00007 * regarding copyright ownership. The ASF licenses this file 00008 * to you under the Apache License, Version 2.0 (the 00009 * "License"); you may not use this file except in compliance 00010 * with the License. You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, 00015 * software distributed under the License is distributed on an 00016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00017 * KIND, either express or implied. See the License for the 00018 * specific language governing permissions and limitations 00019 * under the License. 00020 * ==================================================================== 00021 * @endcopyright 00022 * 00023 * @file svn_hash.h 00024 * @brief Dumping and reading hash tables to/from files. 00025 */ 00026 00027 00028 #ifndef SVN_HASH_H 00029 #define SVN_HASH_H 00030 00031 #include <apr.h> 00032 #include <apr_pools.h> 00033 #include <apr_hash.h> 00034 #include <apr_tables.h> 00035 #include <apr_file_io.h> /* for apr_file_t */ 00036 00037 #include "svn_types.h" 00038 #include "svn_io.h" /* for svn_stream_t */ 00039 00040 00041 #ifdef __cplusplus 00042 extern "C" { 00043 #endif /* __cplusplus */ 00044 00045 00046 /** The longest the "K <number>" line can be in one of our hashdump files. */ 00047 #define SVN_KEYLINE_MAXLEN 100 00048 00049 /** 00050 * @defgroup svn_hash_support Hash table serialization support 00051 * @{ 00052 */ 00053 00054 /*----------------------------------------------------*/ 00055 00056 /** Reading/writing hashtables to disk 00057 * 00058 * @defgroup svn_hash_read_write Reading and writing hashtables to disk 00059 * @{ 00060 */ 00061 00062 /** 00063 * The conventional terminator for hash dumps. 00064 * 00065 * @since New in 1.1. 00066 */ 00067 #define SVN_HASH_TERMINATOR "END" 00068 00069 /** 00070 * Read a hash table from @a stream, storing the resultants names and 00071 * values in @a hash. Use a @a pool for all allocations. @a hash will 00072 * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values. 00073 * If @a terminator is NULL, expect the hash to be terminated by the 00074 * end of the stream; otherwise, expect the hash to be terminated by a 00075 * line containing @a terminator. Pass @c SVN_HASH_TERMINATOR to use 00076 * the conventional terminator "END". 00077 * 00078 * @since New in 1.1. 00079 */ 00080 svn_error_t * 00081 svn_hash_read2(apr_hash_t *hash, 00082 svn_stream_t *stream, 00083 const char *terminator, 00084 apr_pool_t *pool); 00085 00086 /** 00087 * Dump @a hash to @a stream. Use @a pool for all allocations. @a 00088 * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt> 00089 * values. If @a terminator is not NULL, terminate the hash with a 00090 * line containing @a terminator. 00091 * 00092 * @since New in 1.1. 00093 */ 00094 svn_error_t * 00095 svn_hash_write2(apr_hash_t *hash, 00096 svn_stream_t *stream, 00097 const char *terminator, 00098 apr_pool_t *pool); 00099 00100 /** 00101 * Similar to svn_hash_read2(), but allows @a stream to contain 00102 * deletion lines which remove entries from @a hash as well as adding 00103 * to it. 00104 * 00105 * @since New in 1.1. 00106 */ 00107 svn_error_t * 00108 svn_hash_read_incremental(apr_hash_t *hash, 00109 svn_stream_t *stream, 00110 const char *terminator, 00111 apr_pool_t *pool); 00112 00113 /** 00114 * Similar to svn_hash_write2(), but only writes out entries for 00115 * keys which differ between @a hash and @a oldhash, and also writes 00116 * out deletion lines for keys which are present in @a oldhash but not 00117 * in @a hash. 00118 * 00119 * @since New in 1.1. 00120 */ 00121 svn_error_t * 00122 svn_hash_write_incremental(apr_hash_t *hash, 00123 apr_hash_t *oldhash, 00124 svn_stream_t *stream, 00125 const char *terminator, 00126 apr_pool_t *pool); 00127 00128 /** 00129 * This function behaves like svn_hash_read2(), but it only works 00130 * on an apr_file_t input, empty files are accepted, and the hash is 00131 * expected to be terminated with a line containing "END" or 00132 * "PROPS-END". 00133 * 00134 * @deprecated Provided for backward compatibility with the 1.0 API. 00135 */ 00136 SVN_DEPRECATED 00137 svn_error_t * 00138 svn_hash_read(apr_hash_t *hash, 00139 apr_file_t *srcfile, 00140 apr_pool_t *pool); 00141 00142 /** 00143 * This function behaves like svn_hash_write2(), but it only works 00144 * on an apr_file_t output, and the terminator is always "END". 00145 * 00146 * @deprecated Provided for backward compatibility with the 1.0 API. 00147 */ 00148 SVN_DEPRECATED 00149 svn_error_t * 00150 svn_hash_write(apr_hash_t *hash, 00151 apr_file_t *destfile, 00152 apr_pool_t *pool); 00153 00154 /** @} */ 00155 00156 00157 /** Taking the "diff" of two hash tables. 00158 * 00159 * @defgroup svn_hash_diff Taking the diff of two hash tables. 00160 * @{ 00161 */ 00162 00163 /** Hash key status indicator for svn_hash_diff_func_t. */ 00164 enum svn_hash_diff_key_status 00165 { 00166 /* Key is present in both hashes. */ 00167 svn_hash_diff_key_both, 00168 00169 /* Key is present in first hash only. */ 00170 svn_hash_diff_key_a, 00171 00172 /* Key is present in second hash only. */ 00173 svn_hash_diff_key_b 00174 }; 00175 00176 00177 /** Function type for expressing a key's status between two hash tables. */ 00178 typedef svn_error_t *(*svn_hash_diff_func_t) 00179 (const void *key, apr_ssize_t klen, 00180 enum svn_hash_diff_key_status status, 00181 void *baton); 00182 00183 00184 /** Take the diff of two hashtables. 00185 * 00186 * For each key in the union of @a hash_a's and @a hash_b's keys, invoke 00187 * @a diff_func exactly once, passing the key, the key's length, an enum 00188 * @c svn_hash_diff_key_status indicating which table(s) the key appears 00189 * in, and @a diff_func_baton. 00190 * 00191 * Process all keys of @a hash_a first, then all remaining keys of @a hash_b. 00192 * 00193 * If @a diff_func returns error, return that error immediately, without 00194 * applying @a diff_func to anything else. 00195 * 00196 * @a hash_a or @a hash_b or both may be NULL; treat a null table as though 00197 * empty. 00198 * 00199 * Use @a pool for temporary allocation. 00200 */ 00201 svn_error_t * 00202 svn_hash_diff(apr_hash_t *hash_a, 00203 apr_hash_t *hash_b, 00204 svn_hash_diff_func_t diff_func, 00205 void *diff_func_baton, 00206 apr_pool_t *pool); 00207 00208 /** @} */ 00209 00210 00211 /** 00212 * @defgroup svn_hash_misc Miscellaneous hash APIs 00213 * @{ 00214 */ 00215 00216 /** 00217 * Return the keys to @a hash in @a *array. The keys are assumed to be 00218 * (const char *). The keys are in no particular order. 00219 * 00220 * @a *array itself is allocated in @a pool; however, the keys are not 00221 * copied from the hash. 00222 * 00223 * @since New in 1.5. 00224 */ 00225 svn_error_t * 00226 svn_hash_keys(apr_array_header_t **array, 00227 apr_hash_t *hash, 00228 apr_pool_t *pool); 00229 00230 /** 00231 * Set @a *hash to a new hash whose keys come from the items in @a keys 00232 * (an array of <tt>const char *</tt> items), and whose values are 00233 * match their corresponding key. Use @a pool for all allocations 00234 * (including @a *hash, its keys, and its values). 00235 * 00236 * @since New in 1.5. 00237 */ 00238 svn_error_t * 00239 svn_hash_from_cstring_keys(apr_hash_t **hash, 00240 const apr_array_header_t *keys, 00241 apr_pool_t *pool); 00242 00243 /** 00244 * Clear any key/value pairs in the hash table. A wrapper for a 00245 * apr_hash_clear(), which isn't available until APR 1.3.0. 00246 * 00247 * @since New in 1.5. 00248 */ 00249 svn_error_t * 00250 svn_hash__clear(apr_hash_t *hash, apr_pool_t *pool); 00251 00252 /** @} */ 00253 00254 00255 /** 00256 * @defgroup svn_hash_getters Specialized getter APIs for hashes 00257 * @{ 00258 */ 00259 00260 /** Find the value of a @a key in @a hash, return the value. 00261 * 00262 * If @a hash is @c NULL or if the @a key cannot be found, the 00263 * @a default_value will be returned. 00264 * 00265 * @since New in 1.7. 00266 */ 00267 const char * 00268 svn_hash__get_cstring(apr_hash_t *hash, 00269 const char *key, 00270 const char *default_value); 00271 00272 /** Like svn_hash_get_cstring(), but for boolean values. 00273 * 00274 * Parses the value as a boolean value. The recognized representations 00275 * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not 00276 * matter. 00277 * 00278 * @since New in 1.7. 00279 */ 00280 svn_boolean_t 00281 svn_hash__get_bool(apr_hash_t *hash, 00282 const char *key, 00283 svn_boolean_t default_value); 00284 00285 /** @} */ 00286 00287 /** @} */ 00288 00289 #ifdef __cplusplus 00290 } 00291 #endif /* __cplusplus */ 00292 00293 #endif /* SVN_HASH_H */