icuSources/common/uarrsort.h

   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
  26 U_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  */
  41 typedef int32_t U_CALLCONV
  42 UComparator(const void *context, const void *left, const void *right);
  43 U_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  */
  60 U_CAPI void U_EXPORT2
  61 uprv_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  */
  69 U_CAPI int32_t U_EXPORT2
  70 uprv_uint16Comparator(const void *context, const void *left, const void *right);
  71
  72 /**
  73  * Convenience UComparator implementation for int32_t arrays.
  74  * @internal
  75  */
  76 U_CAPI int32_t U_EXPORT2
  77 uprv_int32Comparator(const void *context, const void *left, const void *right);
  78
  79 /**
  80  * Convenience UComparator implementation for uint32_t arrays.
  81  * @internal
  82  */
  83 U_CAPI int32_t U_EXPORT2
  84 uprv_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  */
  99 U_CAPI int32_t U_EXPORT2
 100 uprv_stableBinarySearch(char *array, int32_t length, void *item, int32_t itemSize,
 101                         UComparator *cmp, const void *context);
 102
 103 #endif