Home | History | Annotate | Download | only in common
      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 
     24 U_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  */
     39 typedef int32_t U_CALLCONV
     40 UComparator(const void *context, const void *left, const void *right);
     41 U_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  */
     58 U_CAPI void U_EXPORT2
     59 uprv_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  */
     67 U_CAPI int32_t U_EXPORT2
     68 uprv_uint16Comparator(const void *context, const void *left, const void *right);
     69 
     70 /**
     71  * Convenience UComparator implementation for int32_t arrays.
     72  * @internal
     73  */
     74 U_CAPI int32_t U_EXPORT2
     75 uprv_int32Comparator(const void *context, const void *left, const void *right);
     76 
     77 /**
     78  * Convenience UComparator implementation for uint32_t arrays.
     79  * @internal
     80  */
     81 U_CAPI int32_t U_EXPORT2
     82 uprv_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  */
     97 U_CAPI int32_t U_EXPORT2
     98 uprv_stableBinarySearch(char *array, int32_t length, void *item, int32_t itemSize,
     99                         UComparator *cmp, const void *context);
    100 
    101 #endif
    102