contrib/subversion/subversion/include/svn_sorts.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_sorts.h
  24  * @brief all sorts of sorts.
  25  */
  26
  27
  28 #ifndef SVN_SORTS_H
  29 #define SVN_SORTS_H
  30
  31 #include <apr.h>         /* for apr_ssize_t */
  32 #include <apr_pools.h>   /* for apr_pool_t */
  33 #include <apr_tables.h>  /* for apr_array_header_t */
  34 #include <apr_hash.h>    /* for apr_hash_t */
  35
  36 /* Define a MAX macro if we don't already have one */
  37 #ifndef MAX
  38 #define MAX(a, b) ((a) < (b) ? (b) : (a))
  39 #endif
  40
  41 /* Define a MIN macro if we don't already have one */
  42 #ifndef MIN
  43 #define MIN(a, b) ((a) < (b) ? (a) : (b))
  44 #endif
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif /* __cplusplus */
  49
  50 \f
  51
  52 /** This structure is used to hold a key/value from a hash table.
  53  * @note Private. For use by Subversion's own code only. See issue #1644.
  54  */
  55 typedef struct svn_sort__item_t svn_sort__item_t;
  56
  57
  58 /** Compare two @c svn_sort__item_t's, returning an integer greater than,
  59  * equal to, or less than 0, according to whether the key of @a a is
  60  * greater than, equal to, or less than the key of @a b as determined
  61  * by comparing them with svn_path_compare_paths().
  62  *
  63  * The key strings must be NULL-terminated, even though klen does not
  64  * include the terminator.
  65  *
  66  * This is useful for converting a hash into a sorted
  67  * @c apr_array_header_t.  For example, to convert hash @a hsh to a sorted
  68  * array, do this:
  69  *
  70  * @code
  71      apr_array_header_t *array;
  72      array = svn_sort__hash(hsh, svn_sort_compare_items_as_paths, pool);
  73    @endcode
  74  *
  75  * This function works like svn_sort_compare_items_lexically() except that it
  76  * orders children in subdirectories directly after their parents. This allows
  77  * using the given ordering for a depth first walk, but at a performance
  78  * penalty. Code that doesn't need this special behavior for children, e.g. when
  79  * sorting files at a single directory level should use
  80  * svn_sort_compare_items_lexically() instead.
  81  */
  82 int
  83 svn_sort_compare_items_as_paths(const svn_sort__item_t *a,
  84                                 const svn_sort__item_t *b);
  85
  86
  87 /** Compare two @c svn_sort__item_t's, returning an integer greater than,
  88  * equal to, or less than 0, according as @a a is greater than, equal to,
  89  * or less than @a b according to a lexical key comparison.  The keys are
  90  * not required to be zero-terminated.
  91  */
  92 int
  93 svn_sort_compare_items_lexically(const svn_sort__item_t *a,
  94                                  const svn_sort__item_t *b);
  95
  96 /** Compare two @c svn_revnum_t's, returning an integer greater than, equal
  97  * to, or less than 0, according as @a b is greater than, equal to, or less
  98  * than @a a. Note that this sorts newest revision to oldest (IOW, descending
  99  * order).
 100  *
 101  * This function is compatible for use with qsort().
 102  *
 103  * This is useful for converting an array of revisions into a sorted
 104  * @c apr_array_header_t. You are responsible for detecting, preventing or
 105  * removing duplicates.
 106  */
 107 int
 108 svn_sort_compare_revisions(const void *a,
 109                            const void *b);
 110
 111
 112 /**
 113  * Compare two @c const char * paths, @a *a and @a *b, returning an
 114  * integer greater than, equal to, or less than 0, using the same
 115  * comparison rules as are used by svn_path_compare_paths().
 116  *
 117  * This function is compatible for use with qsort().
 118  *
 119  * @since New in 1.1.
 120  */
 121 int
 122 svn_sort_compare_paths(const void *a,
 123                        const void *b);
 124
 125 /**
 126  * Compare two @c svn_merge_range_t *'s, @a *a and @a *b, returning an
 127  * integer greater than, equal to, or less than 0 if the first range is
 128  * greater than, equal to, or less than, the second range.
 129  *
 130  * Both @c svn_merge_range_t *'s must describe forward merge ranges.
 131  *
 132  * If @a *a and @a *b intersect then the range with the lower start revision
 133  * is considered the lesser range.  If the ranges' start revisions are
 134  * equal then the range with the lower end revision is considered the
 135  * lesser range.
 136  *
 137  * @since New in 1.5
 138  */
 139 int
 140 svn_sort_compare_ranges(const void *a,
 141                         const void *b);
 142
 143 #ifdef __cplusplus
 144 }
 145 #endif /* __cplusplus */
 146
 147 #endif /* SVN_SORTS_H */