Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

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 /*----------------------------------------------------*/
00045 
00046 /** Reading/writing hashtables to disk
00047  *
00048  * @defgroup svn_hash_read_write reading and writing hashtables to disk
00049  * @{
00050  */
00051 
00052 /**
00053  * The conventional terminator for hash dumps.
00054  *
00055  * @since New in 1.1.
00056  */
00057 #define SVN_HASH_TERMINATOR "END"
00058 
00059 /**
00060  * Read a hash table from @a stream, storing the resultants names and
00061  * values in @a hash.  Use a @a pool for all allocations.  @a hash will
00062  * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values.
00063  * If @a terminator is NULL, expect the hash to be terminated by the
00064  * end of the stream; otherwise, expect the hash to be terminated by a
00065  * line containing @a terminator.  Pass @c SVN_HASH_TERMINATOR to use
00066  * the conventional terminator "END".
00067  *
00068  * @since New in 1.1.
00069  */
00070 svn_error_t *svn_hash_read2(apr_hash_t *hash,
00071                             svn_stream_t *stream,
00072                             const char *terminator,
00073                             apr_pool_t *pool);
00074 
00075 /**
00076  * Dump @a hash to @a stream.  Use @a pool for all allocations.  @a
00077  * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt>
00078  * values.  If @a terminator is not NULL, terminate the hash with a
00079  * line containing @a terminator.
00080  *
00081  * @since New in 1.1.
00082  */
00083 svn_error_t *svn_hash_write2(apr_hash_t *hash, 
00084                              svn_stream_t *stream,
00085                              const char *terminator,
00086                              apr_pool_t *pool);
00087 
00088 /**
00089  * Similar to svn_hash_read2(), but allows @a stream to contain
00090  * deletion lines which remove entries from @a hash as well as adding
00091  * to it.
00092  *
00093  * @since New in 1.1.
00094  */
00095 svn_error_t *svn_hash_read_incremental(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_write2(), but only writes out entries for
00102  * keys which differ between @a hash and @a oldhash, and also writes
00103  * out deletion lines for keys which are present in @a oldhash but not
00104  * in @a hash.
00105  *
00106  * @since New in 1.1.
00107  */
00108 svn_error_t *svn_hash_write_incremental(apr_hash_t *hash,
00109                                         apr_hash_t *oldhash,
00110                                         svn_stream_t *stream,
00111                                         const char *terminator,
00112                                         apr_pool_t *pool);
00113 
00114 /**
00115  * This function behaves like svn_hash_read2(), but it only works
00116  * on an apr_file_t input, empty files are accepted, and the hash is
00117  * expected to be terminated with a line containing "END" or
00118  * "PROPS-END".
00119  *
00120  * @deprecated Provided for backward compatibility with the 1.0 API.
00121  */
00122 svn_error_t *svn_hash_read(apr_hash_t *hash, 
00123                            apr_file_t *srcfile,
00124                            apr_pool_t *pool);
00125 
00126 /**
00127  * This function behaves like svn_hash_write2(), but it only works
00128  * on an apr_file_t output, and the terminator is always "END".
00129  *
00130  * @deprecated Provided for backward compatibility with the 1.0 API.
00131  */
00132 svn_error_t *svn_hash_write(apr_hash_t *hash, 
00133                             apr_file_t *destfile,
00134                             apr_pool_t *pool);
00135 
00136 /** @} */
00137 
00138 
00139 /** Taking the "diff" of two hash tables.
00140  *
00141  * @defgroup svn_hash_diff taking the diff of two hash tables.
00142  * @{
00143  */
00144 
00145 /** Hash key status indicator for svn_hash_diff_func_t.  */
00146 enum svn_hash_diff_key_status
00147   {
00148     /* Key is present in both hashes. */
00149     svn_hash_diff_key_both,
00150 
00151     /* Key is present in first hash only. */
00152     svn_hash_diff_key_a,
00153 
00154     /* Key is present in second hash only. */
00155     svn_hash_diff_key_b
00156   };
00157 
00158 
00159 /** Function type for expressing a key's status between two hash tables. */
00160 typedef svn_error_t *(*svn_hash_diff_func_t)
00161   (const void *key, apr_ssize_t klen,
00162    enum svn_hash_diff_key_status status,
00163    void *baton);
00164 
00165 
00166 /** Take the diff of two hashtables.
00167  *
00168  * For each key in the union of @a hash_a's and @a hash_b's keys, invoke
00169  * @a diff_func exactly once, passing the key, the key's length, an enum
00170  * @c svn_hash_diff_key_status indicating which table(s) the key appears
00171  * in, and @a diff_func_baton.
00172  *
00173  * Process all keys of @a hash_a first, then all remaining keys of @a hash_b. 
00174  *
00175  * If @a diff_func returns error, return that error immediately, without
00176  * applying @a diff_func to anything else.
00177  *
00178  * @a hash_a or @a hash_b or both may be null; treat a null table as though
00179  * empty.
00180  *
00181  * Use @a pool for temporary allocation.
00182  */
00183 svn_error_t *svn_hash_diff(apr_hash_t *hash_a,
00184                            apr_hash_t *hash_b,
00185                            svn_hash_diff_func_t diff_func,
00186                            void *diff_func_baton,
00187                            apr_pool_t *pool);
00188 
00189 /** @} */
00190 
00191 #ifdef __cplusplus
00192 }
00193 #endif /* __cplusplus */
00194 
00195 #endif /* SVN_HASH_H */

Generated on Sun Mar 16 14:48:43 2008 for Subversion by doxygen 1.3.5