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
47extern "C" {
48#endif /* __cplusplus */
49
50
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 */
55typedef 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 */
82int
83svn_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 */
92int
93svn_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 */
107int
108svn_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 */
121int
122svn_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 */
139int
140svn_sort_compare_ranges(const void *a,
141                        const void *b);
142
143#ifdef __cplusplus
144}
145#endif /* __cplusplus */
146
147#endif /* SVN_SORTS_H */
148