subversion/include/svn_iter.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2007 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_iter.h
  19  * @brief The Subversion Iteration drivers helper routines
  20  *
  21  */
  22
  23 #include <apr_hash.h>
  24
  25 #include "svn_types.h"
  26 #include "svn_error.h"
  27 #include "svn_pools.h"
  28
  29
  30 /** Callback function for use with svn_iter_apr_hash().
  31  * Use @a pool for temporary allocation, it's cleared between invocations.
  32  *
  33  * @a key, @a klen and @a val are the values normally retrieved with
  34  * apr_hash_this().
  35  *
  36  * @a baton is the baton passed into svn_iter_apr_hash().
  37  *
  38  * @since New in 1.5.
  39  */
  40 typedef svn_error_t *(*svn_iter_apr_hash_cb_t)(void *baton,
  41                                                const void *key,
  42                                                apr_ssize_t klen,
  43                                                void *val, apr_pool_t *pool);
  44
  45 /** Iterate over the elements in @a hash, calling @a func for each one until
  46  * there are no more elements or @a func returns an error.
  47  *
  48  * Uses @a pool for temporary allocations.
  49  *
  50  * If @a completed is not NULL, then on return - if @a func returns no
  51  * errors - @a *completed will be set to @c TRUE.
  52  *
  53  * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that
  54  * error is returned.  When @a func returns @c SVN_ERR_ITER_BREAK,
  55  * iteration is interrupted, but no error is returned and @a *completed is
  56  * set to @c FALSE.
  57  *
  58  * @since New in 1.5.
  59  */
  60 svn_error_t *
  61 svn_iter_apr_hash(svn_boolean_t *completed,
  62                   apr_hash_t *hash,
  63                   svn_iter_apr_hash_cb_t func,
  64                   void *baton,
  65                   apr_pool_t *pool);
  66
  67 /** Iteration callback used in conjuction with svn_iter_apr_array().
  68  *
  69  * Use @a pool for temporary allocation, it's cleared between invocations.
  70  *
  71  * @a baton is the baton passed to svn_iter_apr_array().  @a item
  72  * is a pointer to the item written to the array with the APR_ARRAY_PUSH()
  73  * macro.
  74  *
  75  * @since New in 1.5.
  76  */
  77 typedef svn_error_t *(*svn_iter_apr_array_cb_t)(void *baton,
  78                                                 void *item,
  79                                                 apr_pool_t *pool);
  80
  81 /** Iterate over the elements in @a array calling @a func for each one until
  82  * there are no more elements or @a func returns an error.
  83  *
  84  * Uses @a pool for temporary allocations.
  85  *
  86  * If @a completed is not NULL, then on return - if @a func returns no
  87  * errors - @a *completed will be set to @c TRUE.
  88  *
  89  * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that
  90  * error is returned.  When @a func returns @c SVN_ERR_ITER_BREAK,
  91  * iteration is interrupted, but no error is returned and @a *completed is
  92  * set to @c FALSE.
  93  *
  94  * @since New in 1.5.
  95  */
  96 svn_error_t *
  97 svn_iter_apr_array(svn_boolean_t *completed,
  98                    const apr_array_header_t *array,
  99                    svn_iter_apr_array_cb_t func,
 100                    void *baton,
 101                    apr_pool_t *pool);
 102
 103
 104 /** Internal routine used by svn_iter_break() macro.
 105  */
 106 svn_error_t *
 107 svn_iter__break(void);
 108
 109 /** Helper macro to break looping in svn_iter_apr_array() and
 110  * svn_iter_apr_hash() driven loops.
 111  *
 112  * @note The error is just a means of communicating between
 113  *       driver and callback.  There is no need for it to exist
 114  *       past the lifetime of the iterpool.
 115  *
 116  * @since New in 1.5.
 117  */
 118 #define svn_iter_break(pool) return svn_iter__break()