Main Page   Modules   Data Structures   File List   Data Fields  

svn_hash.h

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

Generated on Wed Aug 31 03:26:15 2005 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002