svn_hash.h

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

Generated on Sun Mar 1 17:18:33 2009 for Subversion by  doxygen 1.4.7