- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# 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