Subversion
svn_hash.h
Go to the documentation of this file.
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 */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines