Subversion 1.6.16

svn_hash.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004, 2008 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_hash.h
00019  * @brief Dumping and reading hash tables to/from files.
00020  */
00021 
00022 
00023 #ifndef SVN_HASH_H
00024 #define SVN_HASH_H
00025 
00026 #include <apr.h>
00027 #include <apr_pools.h>
00028 #include <apr_hash.h>
00029 #include <apr_tables.h>
00030 #include <apr_file_io.h>  /* for apr_file_t */
00031 
00032 #include "svn_types.h"
00033 #include "svn_io.h"       /* for svn_stream_t */
00034 
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif /* __cplusplus */
00039 
00040 
00041 /** The longest the "K <number>" line can be in one of our hashdump files. */
00042 #define SVN_KEYLINE_MAXLEN 100
00043 
00044 /**
00045  * @defgroup svn_hash_support Hash table serialization support
00046  * @{
00047  */
00048 
00049 /*----------------------------------------------------*/
00050 
00051 /** Reading/writing hashtables to disk
00052  *
00053  * @defgroup svn_hash_read_write Reading and writing hashtables to disk
00054  * @{
00055  */
00056 
00057 /**
00058  * The conventional terminator for hash dumps.
00059  *
00060  * @since New in 1.1.
00061  */
00062 #define SVN_HASH_TERMINATOR "END"
00063 
00064 /**
00065  * Read a hash table from @a stream, storing the resultants names and
00066  * values in @a hash.  Use a @a pool for all allocations.  @a hash will
00067  * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values.
00068  * If @a terminator is NULL, expect the hash to be terminated by the
00069  * end of the stream; otherwise, expect the hash to be terminated by a
00070  * line containing @a terminator.  Pass @c SVN_HASH_TERMINATOR to use
00071  * the conventional terminator "END".
00072  *
00073  * @since New in 1.1.
00074  */
00075 svn_error_t *
00076 svn_hash_read2(apr_hash_t *hash,
00077                svn_stream_t *stream,
00078                const char *terminator,
00079                apr_pool_t *pool);
00080 
00081 /**
00082  * Dump @a hash to @a stream.  Use @a pool for all allocations.  @a
00083  * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt>
00084  * values.  If @a terminator is not NULL, terminate the hash with a
00085  * line containing @a terminator.
00086  *
00087  * @since New in 1.1.
00088  */
00089 svn_error_t *
00090 svn_hash_write2(apr_hash_t *hash,
00091                 svn_stream_t *stream,
00092                 const char *terminator,
00093                 apr_pool_t *pool);
00094 
00095 /**
00096  * Similar to svn_hash_read2(), but allows @a stream to contain
00097  * deletion lines which remove entries from @a hash as well as adding
00098  * to it.
00099  *
00100  * @since New in 1.1.
00101  */
00102 svn_error_t *
00103 svn_hash_read_incremental(apr_hash_t *hash,
00104                           svn_stream_t *stream,
00105                           const char *terminator,
00106                           apr_pool_t *pool);
00107 
00108 /**
00109  * Similar to svn_hash_write2(), but only writes out entries for
00110  * keys which differ between @a hash and @a oldhash, and also writes
00111  * out deletion lines for keys which are present in @a oldhash but not
00112  * in @a hash.
00113  *
00114  * @since New in 1.1.
00115  */
00116 svn_error_t *
00117 svn_hash_write_incremental(apr_hash_t *hash,
00118                            apr_hash_t *oldhash,
00119                            svn_stream_t *stream,
00120                            const char *terminator,
00121                            apr_pool_t *pool);
00122 
00123 /**
00124  * This function behaves like svn_hash_read2(), but it only works
00125  * on an apr_file_t input, empty files are accepted, and the hash is
00126  * expected to be terminated with a line containing "END" or
00127  * "PROPS-END".
00128  *
00129  * @deprecated Provided for backward compatibility with the 1.0 API.
00130  */
00131 SVN_DEPRECATED
00132 svn_error_t *
00133 svn_hash_read(apr_hash_t *hash,
00134               apr_file_t *srcfile,
00135               apr_pool_t *pool);
00136 
00137 /**
00138  * This function behaves like svn_hash_write2(), but it only works
00139  * on an apr_file_t output, and the terminator is always "END".
00140  *
00141  * @deprecated Provided for backward compatibility with the 1.0 API.
00142  */
00143 SVN_DEPRECATED
00144 svn_error_t *
00145 svn_hash_write(apr_hash_t *hash,
00146                apr_file_t *destfile,
00147                apr_pool_t *pool);
00148 
00149 /** @} */
00150 
00151 
00152 /** Taking the "diff" of two hash tables.
00153  *
00154  * @defgroup svn_hash_diff Taking the diff of two hash tables.
00155  * @{
00156  */
00157 
00158 /** Hash key status indicator for svn_hash_diff_func_t.  */
00159 enum svn_hash_diff_key_status
00160   {
00161     /* Key is present in both hashes. */
00162     svn_hash_diff_key_both,
00163 
00164     /* Key is present in first hash only. */
00165     svn_hash_diff_key_a,
00166 
00167     /* Key is present in second hash only. */
00168     svn_hash_diff_key_b
00169   };
00170 
00171 
00172 /** Function type for expressing a key's status between two hash tables. */
00173 typedef svn_error_t *(*svn_hash_diff_func_t)
00174   (const void *key, apr_ssize_t klen,
00175    enum svn_hash_diff_key_status status,
00176    void *baton);
00177 
00178 
00179 /** Take the diff of two hashtables.
00180  *
00181  * For each key in the union of @a hash_a's and @a hash_b's keys, invoke
00182  * @a diff_func exactly once, passing the key, the key's length, an enum
00183  * @c svn_hash_diff_key_status indicating which table(s) the key appears
00184  * in, and @a diff_func_baton.
00185  *
00186  * Process all keys of @a hash_a first, then all remaining keys of @a hash_b.
00187  *
00188  * If @a diff_func returns error, return that error immediately, without
00189  * applying @a diff_func to anything else.
00190  *
00191  * @a hash_a or @a hash_b or both may be NULL; treat a null table as though
00192  * empty.
00193  *
00194  * Use @a pool for temporary allocation.
00195  */
00196 svn_error_t *
00197 svn_hash_diff(apr_hash_t *hash_a,
00198               apr_hash_t *hash_b,
00199               svn_hash_diff_func_t diff_func,
00200               void *diff_func_baton,
00201               apr_pool_t *pool);
00202 
00203 /** @} */
00204 
00205 
00206 /**
00207  * @defgroup svn_hash_misc Miscellaneous hash APIs
00208  * @{
00209  */
00210 
00211 /**
00212  * Return the keys to @a hash in @a *array.  The keys are assumed to be
00213  * (const char *).  The keys are in no particular order.
00214  *
00215  * @a *array itself is allocated in @a pool; however, the keys are not
00216  * copied from the hash.
00217  *
00218  * @since New in 1.5.
00219  */
00220 svn_error_t *
00221 svn_hash_keys(apr_array_header_t **array,
00222               apr_hash_t *hash,
00223               apr_pool_t *pool);
00224 
00225 /**
00226  * Set @a *hash to a new hash whose keys come from the items in @a keys
00227  * (an array of <tt>const char *</tt> items), and whose values are
00228  * match their corresponding key.  Use @a pool for all allocations
00229  * (including @a *hash, its keys, and its values).
00230  *
00231  * @since New in 1.5.
00232  */
00233 svn_error_t *
00234 svn_hash_from_cstring_keys(apr_hash_t **hash,
00235                            const apr_array_header_t *keys,
00236                            apr_pool_t *pool);
00237 
00238 /**
00239  * Clear any key/value pairs in the hash table.  A wrapper for a
00240  * apr_hash_clear(), which isn't available until APR 1.3.0.
00241  *
00242  * @since New in 1.5.
00243  */
00244 svn_error_t *
00245 svn_hash__clear(apr_hash_t *hash);
00246 
00247 /** @} */
00248 
00249 /** @} */
00250 
00251 #ifdef __cplusplus
00252 }
00253 #endif /* __cplusplus */
00254 
00255 #endif /* SVN_HASH_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines