svn_sorts.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_sorts.h
00019  * @brief all sorts of sorts.
00020  */
00021 
00022 
00023 #ifndef SVN_SORTS_H
00024 #define SVN_SORTS_H
00025 
00026 #include <apr_pools.h>
00027 #include <apr_tables.h>         /* for apr_array_header_t */
00028 #include <apr_hash.h>
00029 
00030 /* Define a MAX macro if we don't already have one */
00031 #ifndef MAX
00032 #define MAX(a, b) ((a) < (b) ? (b) : (a))
00033 #endif
00034 
00035 /* Define a MIN macro if we don't already have one */
00036 #ifndef MIN
00037 #define MIN(a, b) ((a) < (b) ? (a) : (b))
00038 #endif
00039 
00040 #ifdef __cplusplus
00041 extern "C" {
00042 #endif /* __cplusplus */
00043 
00044 
00045 
00046 /** This structure is used to hold a key/value from a hash table.
00047  * @note Private. For use by Subversion's own code only. See issue #1644.
00048  */
00049 typedef struct svn_sort__item_t {
00050   /** pointer to the key */
00051   const void *key;
00052 
00053   /** size of the key */
00054   apr_ssize_t klen;
00055 
00056   /** pointer to the value */
00057   void *value;
00058 } svn_sort__item_t;
00059 
00060 
00061 /** Compare two @c svn_sort__item_t's, returning an integer greater than,
00062  * equal to, or less than 0, according to whether the key of @a a is
00063  * greater than, equal to, or less than the key of @a b as determined
00064  * by comparing them with svn_path_compare_paths().
00065  *
00066  * The key strings must be NULL-terminated, even though klen does not
00067  * include the terminator.
00068  *
00069  * This is useful for converting a hash into a sorted
00070  * @c apr_array_header_t.  For example, to convert hash @a hsh to a sorted
00071  * array, do this:
00072  *
00073  * @verbatim
00074      apr_array_header_t *hdr;
00075      hdr = svn_sort__hash (hsh, @c svn_sort_compare_items_as_paths, pool);
00076    @endverbatim
00077  */
00078 int svn_sort_compare_items_as_paths(const svn_sort__item_t *a,
00079                                     const svn_sort__item_t *b);
00080 
00081 
00082 /** Compare two @c svn_sort__item_t's, returning an integer greater than,
00083  * equal to, or less than 0, according as @a a is greater than, equal to,
00084  * or less than @a b according to a lexical key comparison.  The keys are
00085  * not required to be zero-terminated.
00086  */
00087 int svn_sort_compare_items_lexically(const svn_sort__item_t *a,
00088                                      const svn_sort__item_t *b);
00089 
00090 /** Compare two @c svn_revnum_t's, returning an integer greater than, equal
00091  * to, or less than 0, according as @a b is greater than, equal to, or less
00092  * than @a a. Note that this sorts newest revision to oldest (IOW, descending
00093  * order).
00094  *
00095  * This function is compatible for use with qsort().
00096  *
00097  * This is useful for converting an array of revisions into a sorted
00098  * @c apr_array_header_t. You are responsible for detecting, preventing or
00099  * removing duplicates.
00100  */
00101 int svn_sort_compare_revisions(const void *a, const void *b);
00102 
00103 
00104 /**
00105  * Compare two @c const char * paths, returning an integer greater
00106  * than, equal to, or less than 0, using the same comparison rules as
00107  * are used by svn_path_compare_paths().
00108  *
00109  * This function is compatible for use with qsort().
00110  *
00111  * @since New in 1.1.
00112  */
00113 int svn_sort_compare_paths(const void *a, const void *b);
00114 
00115 /**
00116  * Compare two @c svn_merge_range_t *'s, returning an integer greater
00117  * than, equal to, or less than 0 if the first range is greater than,
00118  * equal to, or less than, the second range.
00119  * @since New in 1.5
00120  */
00121 int svn_sort_compare_ranges(const void *a, const void *b);
00122 
00123 /** Sort @a ht according to its keys, return an @c apr_array_header_t
00124  * containing @c svn_sort__item_t structures holding those keys and values
00125  * (i.e. for each @c svn_sort__item_t @a item in the returned array,
00126  * @a item->key and @a item->size are the hash key, and @a item->data points to
00127  * the hash value).
00128  *
00129  * Storage is shared with the original hash, not copied.
00130  *
00131  * @a comparison_func should take two @c svn_sort__item_t's and return an
00132  * integer greater than, equal to, or less than 0, according as the first item
00133  * is greater than, equal to, or less than the second.
00134  *
00135  * @note Private. For use by Subversion's own code only. See issue #1644.
00136  *
00137  * @note This function and the @c svn_sort__item_t should go over to APR.
00138  */
00139 apr_array_header_t *
00140 svn_sort__hash(apr_hash_t *ht,
00141                int (*comparison_func)(const svn_sort__item_t *,
00142                                       const svn_sort__item_t *),
00143                apr_pool_t *pool);
00144 
00145 
00146 #ifdef __cplusplus
00147 }
00148 #endif /* __cplusplus */
00149 
00150 #endif /* SVN_SORTS_H */

Generated on Sat Dec 13 20:31:07 2008 for Subversion by  doxygen 1.3.9.1