1/*
2*******************************************************************************
3*
4*   Copyright (C) 2003-2013, International Business Machines
5*   Corporation and others.  All Rights Reserved.
6*
7*******************************************************************************
8*   file name:  uarrsort.h
9*   encoding:   US-ASCII
10*   tab size:   8 (not used)
11*   indentation:4
12*
13*   created on: 2003aug04
14*   created by: Markus W. Scherer
15*
16*   Internal function for sorting arrays.
17*/
18
19#ifndef __UARRSORT_H__
20#define __UARRSORT_H__
21
22#include "unicode/utypes.h"
23
24U_CDECL_BEGIN
25/**
26 * Function type for comparing two items as part of sorting an array or similar.
27 * Callback function for uprv_sortArray().
28 *
29 * @param context Application-specific pointer, passed through by uprv_sortArray().
30 * @param left    Pointer to the "left" item.
31 * @param right   Pointer to the "right" item.
32 * @return 32-bit signed integer comparison result:
33 *                <0 if left<right
34 *               ==0 if left==right
35 *                >0 if left>right
36 *
37 * @internal
38 */
39typedef int32_t U_CALLCONV
40UComparator(const void *context, const void *left, const void *right);
41U_CDECL_END
42
43/**
44 * Array sorting function.
45 * Uses a UComparator for comparing array items to each other, and simple
46 * memory copying to move items.
47 *
48 * @param array      The array to be sorted.
49 * @param length     The number of items in the array.
50 * @param itemSize   The size in bytes of each array item.
51 * @param cmp        UComparator function used to compare two items each.
52 * @param context    Application-specific pointer, passed through to the UComparator.
53 * @param sortStable If true, a stable sorting algorithm must be used.
54 * @param pErrorCode ICU in/out UErrorCode parameter.
55 *
56 * @internal
57 */
58U_CAPI void U_EXPORT2
59uprv_sortArray(void *array, int32_t length, int32_t itemSize,
60               UComparator *cmp, const void *context,
61               UBool sortStable, UErrorCode *pErrorCode);
62
63/**
64 * Convenience UComparator implementation for uint16_t arrays.
65 * @internal
66 */
67U_CAPI int32_t U_EXPORT2
68uprv_uint16Comparator(const void *context, const void *left, const void *right);
69
70/**
71 * Convenience UComparator implementation for int32_t arrays.
72 * @internal
73 */
74U_CAPI int32_t U_EXPORT2
75uprv_int32Comparator(const void *context, const void *left, const void *right);
76
77/**
78 * Convenience UComparator implementation for uint32_t arrays.
79 * @internal
80 */
81U_CAPI int32_t U_EXPORT2
82uprv_uint32Comparator(const void *context, const void *left, const void *right);
83
84/**
85 * Much like Java Collections.binarySearch(list, key, comparator).
86 *
87 * Except: Java documents "If the list contains multiple elements equal to
88 * the specified object, there is no guarantee which one will be found."
89 *
90 * This version here will return the largest index of any equal item,
91 * for use in stable sorting.
92 *
93 * @return the index>=0 where the item was found:
94 *         the largest such index, if multiple, for stable sorting;
95 *         or the index<0 for inserting the item at ~index in sorted order
96 */
97U_CAPI int32_t U_EXPORT2
98uprv_stableBinarySearch(char *array, int32_t length, void *item, int32_t itemSize,
99                        UComparator *cmp, const void *context);
100
101#endif
102