Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_sorts.h
Go to the documentation of this file.
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 
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  */
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
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
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 */