subversion/include/svn_hash.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_hash.h
  19  * @brief Dumping and reading hash tables to/from files.
  20  */
  21
  22
  23 #ifndef SVN_HASH_H
  24 #define SVN_HASH_H
  25
  26 #include <apr_pools.h>
  27 #include <apr_hash.h>
  28 #include <apr_file_io.h>
  29
  30 #include "svn_types.h"
  31 #include "svn_io.h"
  32 #include "svn_error.h"
  33
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif /* __cplusplus */
  38
  39 \f
  40 /** The longest the "K <number>" line can be in one of our hashdump files. */
  41 #define SVN_KEYLINE_MAXLEN 100
  42
  43 /**
  44  * @defgroup svn_hash_support Hash table serialization support
  45  * @{
  46  */
  47
  48 /*----------------------------------------------------*/
  49 \f
  50 /** Reading/writing hashtables to disk
  51  *
  52  * @defgroup svn_hash_read_write Reading and writing hashtables to disk
  53  * @{
  54  */
  55
  56 /**
  57  * The conventional terminator for hash dumps.
  58  *
  59  * @since New in 1.1.
  60  */
  61 #define SVN_HASH_TERMINATOR "END"
  62
  63 /**
  64  * Read a hash table from @a stream, storing the resultants names and
  65  * values in @a hash.  Use a @a pool for all allocations.  @a hash will
  66  * have <tt>const char *</tt> keys and <tt>svn_string_t *</tt> values.
  67  * If @a terminator is NULL, expect the hash to be terminated by the
  68  * end of the stream; otherwise, expect the hash to be terminated by a
  69  * line containing @a terminator.  Pass @c SVN_HASH_TERMINATOR to use
  70  * the conventional terminator "END".
  71  *
  72  * @since New in 1.1.
  73  */
  74 svn_error_t *svn_hash_read2(apr_hash_t *hash,
  75                             svn_stream_t *stream,
  76                             const char *terminator,
  77                             apr_pool_t *pool);
  78
  79 /**
  80  * Dump @a hash to @a stream.  Use @a pool for all allocations.  @a
  81  * hash has <tt>const char *</tt> keys and <tt>svn_string_t *</tt>
  82  * values.  If @a terminator is not NULL, terminate the hash with a
  83  * line containing @a terminator.
  84  *
  85  * @since New in 1.1.
  86  */
  87 svn_error_t *svn_hash_write2(apr_hash_t *hash,
  88                              svn_stream_t *stream,
  89                              const char *terminator,
  90                              apr_pool_t *pool);
  91
  92 /**
  93  * Similar to svn_hash_read2(), but allows @a stream to contain
  94  * deletion lines which remove entries from @a hash as well as adding
  95  * to it.
  96  *
  97  * @since New in 1.1.
  98  */
  99 svn_error_t *svn_hash_read_incremental(apr_hash_t *hash,
 100                                        svn_stream_t *stream,
 101                                        const char *terminator,
 102                                        apr_pool_t *pool);
 103
 104 /**
 105  * Similar to svn_hash_write2(), but only writes out entries for
 106  * keys which differ between @a hash and @a oldhash, and also writes
 107  * out deletion lines for keys which are present in @a oldhash but not
 108  * in @a hash.
 109  *
 110  * @since New in 1.1.
 111  */
 112 svn_error_t *svn_hash_write_incremental(apr_hash_t *hash,
 113                                         apr_hash_t *oldhash,
 114                                         svn_stream_t *stream,
 115                                         const char *terminator,
 116                                         apr_pool_t *pool);
 117
 118 /**
 119  * This function behaves like svn_hash_read2(), but it only works
 120  * on an apr_file_t input, empty files are accepted, and the hash is
 121  * expected to be terminated with a line containing "END" or
 122  * "PROPS-END".
 123  *
 124  * @deprecated Provided for backward compatibility with the 1.0 API.
 125  */
 126 svn_error_t *svn_hash_read(apr_hash_t *hash,
 127                            apr_file_t *srcfile,
 128                            apr_pool_t *pool);
 129
 130 /**
 131  * This function behaves like svn_hash_write2(), but it only works
 132  * on an apr_file_t output, and the terminator is always "END".
 133  *
 134  * @deprecated Provided for backward compatibility with the 1.0 API.
 135  */
 136 svn_error_t *svn_hash_write(apr_hash_t *hash,
 137                             apr_file_t *destfile,
 138                             apr_pool_t *pool);
 139
 140 /** @} */
 141
 142 \f
 143 /** Taking the "diff" of two hash tables.
 144  *
 145  * @defgroup svn_hash_diff Taking the diff of two hash tables.
 146  * @{
 147  */
 148
 149 /** Hash key status indicator for svn_hash_diff_func_t.  */
 150 enum svn_hash_diff_key_status
 151   {
 152     /* Key is present in both hashes. */
 153     svn_hash_diff_key_both,
 154
 155     /* Key is present in first hash only. */
 156     svn_hash_diff_key_a,
 157
 158     /* Key is present in second hash only. */
 159     svn_hash_diff_key_b
 160   };
 161
 162
 163 /** Function type for expressing a key's status between two hash tables. */
 164 typedef svn_error_t *(*svn_hash_diff_func_t)
 165   (const void *key, apr_ssize_t klen,
 166    enum svn_hash_diff_key_status status,
 167    void *baton);
 168
 169
 170 /** Take the diff of two hashtables.
 171  *
 172  * For each key in the union of @a hash_a's and @a hash_b's keys, invoke
 173  * @a diff_func exactly once, passing the key, the key's length, an enum
 174  * @c svn_hash_diff_key_status indicating which table(s) the key appears
 175  * in, and @a diff_func_baton.
 176  *
 177  * Process all keys of @a hash_a first, then all remaining keys of @a hash_b.
 178  *
 179  * If @a diff_func returns error, return that error immediately, without
 180  * applying @a diff_func to anything else.
 181  *
 182  * @a hash_a or @a hash_b or both may be NULL; treat a null table as though
 183  * empty.
 184  *
 185  * Use @a pool for temporary allocation.
 186  */
 187 svn_error_t *svn_hash_diff(apr_hash_t *hash_a,
 188                            apr_hash_t *hash_b,
 189                            svn_hash_diff_func_t diff_func,
 190                            void *diff_func_baton,
 191                            apr_pool_t *pool);
 192
 193 /** @} */
 194
 195 \f
 196 /**
 197  * @defgroup svn_hash_misc Miscellaneous hash APIs
 198  * @{
 199  */
 200
 201 /**
 202  * Return the keys to @a hash in @a *array.  The keys are assumed to be
 203  * (const char *).  The keys are in no particular order.
 204  *
 205  * @a *array itself is allocated in @a pool; however, the keys are not
 206  * copied from the hash.
 207  *
 208  * @since New in 1.5.
 209  */
 210 svn_error_t *svn_hash_keys(apr_array_header_t **array,
 211                            apr_hash_t *hash,
 212                            apr_pool_t *pool);
 213
 214 /**
 215  * Set @a *hash to a new hash whose keys come from the items in @a keys
 216  * (an array of <tt>const char *</tt> items), and whose values are
 217  * match their corresponding key.  Use @a pool for all allocations
 218  * (including @a *hash, its keys, and its values).
 219  *
 220  * @since New in 1.5.
 221  */
 222 svn_error_t *svn_hash_from_cstring_keys(apr_hash_t **hash,
 223                                         const apr_array_header_t *keys,
 224                                         apr_pool_t *pool);
 225
 226 /**
 227  * Clear any key/value pairs in the hash table.  A wrapper for a
 228  * apr_hash_clear(), which isn't available until APR 1.3.0.
 229  *
 230  * @since New in 1.5.
 231  */
 232 svn_error_t *svn_hash__clear(apr_hash_t *hash);
 233
 234 /** @} */
 235
 236 /** @} */
 237
 238 #ifdef __cplusplus
 239 }
 240 #endif /* __cplusplus */
 241
 242 #endif /* SVN_HASH_H */