subversion/include/svn_sorts.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_sorts.h
  19  * @brief all sorts of sorts.
  20  */
  21
  22
  23 #ifndef SVN_SORTS_H
  24 #define SVN_SORTS_H
  25
  26 #include <apr_pools.h>
  27 #include <apr_tables.h>         /* for apr_array_header_t */
  28 #include <apr_hash.h>
  29
  30 /* Define a MAX macro if we don't already have one */
  31 #ifndef MAX
  32 #define MAX(a, b) ((a) < (b) ? (b) : (a))
  33 #endif
  34
  35 /* Define a MIN macro if we don't already have one */
  36 #ifndef MIN
  37 #define MIN(a, b) ((a) < (b) ? (a) : (b))
  38 #endif
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif /* __cplusplus */
  43
  44 \f
  45
  46 /** This structure is used to hold a key/value from a hash table.
  47  * @note Private. For use by Subversion's own code only. See issue #1644.
  48  */
  49 typedef struct svn_sort__item_t {
  50   /** pointer to the key */
  51   const void *key;
  52
  53   /** size of the key */
  54   apr_ssize_t klen;
  55
  56   /** pointer to the value */
  57   void *value;
  58 } svn_sort__item_t;
  59
  60
  61 /** Compare two @c svn_sort__item_t's, returning an integer greater than,
  62  * equal to, or less than 0, according to whether the key of @a a is
  63  * greater than, equal to, or less than the key of @a b as determined
  64  * by comparing them with svn_path_compare_paths().
  65  *
  66  * The key strings must be NULL-terminated, even though klen does not
  67  * include the terminator.
  68  *
  69  * This is useful for converting a hash into a sorted
  70  * @c apr_array_header_t.  For example, to convert hash @a hsh to a sorted
  71  * array, do this:
  72  *
  73  * @verbatim
  74      apr_array_header_t *hdr;
  75      hdr = svn_sort__hash (hsh, @c svn_sort_compare_items_as_paths, pool);
  76    @endverbatim
  77  */
  78 int svn_sort_compare_items_as_paths(const svn_sort__item_t *a,
  79                                     const svn_sort__item_t *b);
  80
  81
  82 /** Compare two @c svn_sort__item_t's, returning an integer greater than,
  83  * equal to, or less than 0, according as @a a is greater than, equal to,
  84  * or less than @a b according to a lexical key comparison.  The keys are
  85  * not required to be zero-terminated.
  86  */
  87 int svn_sort_compare_items_lexically(const svn_sort__item_t *a,
  88                                      const svn_sort__item_t *b);
  89
  90 /** Compare two @c svn_revnum_t's, returning an integer greater than, equal
  91  * to, or less than 0, according as @a b is greater than, equal to, or less
  92  * than @a a. Note that this sorts newest revision to oldest (IOW, descending
  93  * order).
  94  *
  95  * This function is compatible for use with qsort().
  96  *
  97  * This is useful for converting an array of revisions into a sorted
  98  * @c apr_array_header_t. You are responsible for detecting, preventing or
  99  * removing duplicates.
 100  */
 101 int svn_sort_compare_revisions(const void *a, const void *b);
 102
 103
 104 /**
 105  * Compare two @c const char * paths, returning an integer greater
 106  * than, equal to, or less than 0, using the same comparison rules as
 107  * are used by svn_path_compare_paths().
 108  *
 109  * This function is compatible for use with qsort().
 110  *
 111  * @since New in 1.1.
 112  */
 113 int svn_sort_compare_paths(const void *a, const void *b);
 114
 115 /**
 116  * Compare two @c svn_merge_range_t *'s, returning an integer greater
 117  * than, equal to, or less than 0 if the first range is greater than,
 118  * equal to, or less than, the second range.
 119  * @since New in 1.5
 120  */
 121 int svn_sort_compare_ranges(const void *a, const void *b);
 122
 123 /** Sort @a ht according to its keys, return an @c apr_array_header_t
 124  * containing @c svn_sort__item_t structures holding those keys and values
 125  * (i.e. for each @c svn_sort__item_t @a item in the returned array,
 126  * @a item->key and @a item->size are the hash key, and @a item->data points to
 127  * the hash value).
 128  *
 129  * Storage is shared with the original hash, not copied.
 130  *
 131  * @a comparison_func should take two @c svn_sort__item_t's and return an
 132  * integer greater than, equal to, or less than 0, according as the first item
 133  * is greater than, equal to, or less than the second.
 134  *
 135  * @note Private. For use by Subversion's own code only. See issue #1644.
 136  *
 137  * @note This function and the @c svn_sort__item_t should go over to APR.
 138  */
 139 apr_array_header_t *
 140 svn_sort__hash(apr_hash_t *ht,
 141                int (*comparison_func)(const svn_sort__item_t *,
 142                                       const svn_sort__item_t *),
 143                apr_pool_t *pool);
 144
 145
 146 #ifdef __cplusplus
 147 }
 148 #endif /* __cplusplus */
 149
 150 #endif /* SVN_SORTS_H */