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