icuSources/common/unicode/ucpmap.h

   1 // © 2018 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3
   4 // ucpmap.h
   5 // created: 2018sep03 Markus W. Scherer
   6
   7 #ifndef __UCPMAP_H__
   8 #define __UCPMAP_H__
   9
  10 #include "unicode/utypes.h"
  11
  12 #ifndef U_HIDE_DRAFT_API
  13
  14 U_CDECL_BEGIN
  15
  16 /**
  17  * \file
  18  *
  19  * This file defines an abstract map from Unicode code points to integer values.
  20  *
  21  * @see UCPMap
  22  * @see UCPTrie
  23  * @see UMutableCPTrie
  24  */
  25
  26 /**
  27  * Abstract map from Unicode code points (U+0000..U+10FFFF) to integer values.
  28  *
  29  * @see UCPTrie
  30  * @see UMutableCPTrie
  31  * @draft ICU 63
  32  */
  33 typedef struct UCPMap UCPMap;
  34
  35 /**
  36  * Selectors for how ucpmap_getRange() etc. should report value ranges overlapping with surrogates.
  37  * Most users should use UCPMAP_RANGE_NORMAL.
  38  *
  39  * @see ucpmap_getRange
  40  * @see ucptrie_getRange
  41  * @see umutablecptrie_getRange
  42  * @draft ICU 63
  43  */
  44 enum UCPMapRangeOption {
  45     /**
  46      * ucpmap_getRange() enumerates all same-value ranges as stored in the map.
  47      * Most users should use this option.
  48      * @draft ICU 63
  49      */
  50     UCPMAP_RANGE_NORMAL,
  51     /**
  52      * ucpmap_getRange() enumerates all same-value ranges as stored in the map,
  53      * except that lead surrogates (U+D800..U+DBFF) are treated as having the
  54      * surrogateValue, which is passed to getRange() as a separate parameter.
  55      * The surrogateValue is not transformed via filter().
  56      * See U_IS_LEAD(c).
  57      *
  58      * Most users should use UCPMAP_RANGE_NORMAL instead.
  59      *
  60      * This option is useful for maps that map surrogate code *units* to
  61      * special values optimized for UTF-16 string processing
  62      * or for special error behavior for unpaired surrogates,
  63      * but those values are not to be associated with the lead surrogate code *points*.
  64      * @draft ICU 63
  65      */
  66     UCPMAP_RANGE_FIXED_LEAD_SURROGATES,
  67     /**
  68      * ucpmap_getRange() enumerates all same-value ranges as stored in the map,
  69      * except that all surrogates (U+D800..U+DFFF) are treated as having the
  70      * surrogateValue, which is passed to getRange() as a separate parameter.
  71      * The surrogateValue is not transformed via filter().
  72      * See U_IS_SURROGATE(c).
  73      *
  74      * Most users should use UCPMAP_RANGE_NORMAL instead.
  75      *
  76      * This option is useful for maps that map surrogate code *units* to
  77      * special values optimized for UTF-16 string processing
  78      * or for special error behavior for unpaired surrogates,
  79      * but those values are not to be associated with the lead surrogate code *points*.
  80      * @draft ICU 63
  81      */
  82     UCPMAP_RANGE_FIXED_ALL_SURROGATES
  83 };
  84 #ifndef U_IN_DOXYGEN
  85 typedef enum UCPMapRangeOption UCPMapRangeOption;
  86 #endif
  87
  88 /**
  89  * Returns the value for a code point as stored in the map, with range checking.
  90  * Returns an implementation-defined error value if c is not in the range 0..U+10FFFF.
  91  *
  92  * @param map the map
  93  * @param c the code point
  94  * @return the map value,
  95  *         or an implementation-defined error value if the code point is not in the range 0..U+10FFFF
  96  * @draft ICU 63
  97  */
  98 U_CAPI uint32_t U_EXPORT2
  99 ucpmap_get(const UCPMap *map, UChar32 c);
 100
 101 /**
 102  * Callback function type: Modifies a map value.
 103  * Optionally called by ucpmap_getRange()/ucptrie_getRange()/umutablecptrie_getRange().
 104  * The modified value will be returned by the getRange function.
 105  *
 106  * Can be used to ignore some of the value bits,
 107  * make a filter for one of several values,
 108  * return a value index computed from the map value, etc.
 109  *
 110  * @param context an opaque pointer, as passed into the getRange function
 111  * @param value a value from the map
 112  * @return the modified value
 113  * @draft ICU 63
 114  */
 115 typedef uint32_t U_CALLCONV
 116 UCPMapValueFilter(const void *context, uint32_t value);
 117
 118 /**
 119  * Returns the last code point such that all those from start to there have the same value.
 120  * Can be used to efficiently iterate over all same-value ranges in a map.
 121  * (This is normally faster than iterating over code points and get()ting each value,
 122  * but much slower than a data structure that stores ranges directly.)
 123  *
 124  * If the UCPMapValueFilter function pointer is not NULL, then
 125  * the value to be delivered is passed through that function, and the return value is the end
 126  * of the range where all values are modified to the same actual value.
 127  * The value is unchanged if that function pointer is NULL.
 128  *
 129  * Example:
 130  * \code
 131  * UChar32 start = 0, end;
 132  * uint32_t value;
 133  * while ((end = ucpmap_getRange(map, start, UCPMAP_RANGE_NORMAL, 0,
 134  *                               NULL, NULL, &value)) >= 0) {
 135  *     // Work with the range start..end and its value.
 136  *     start = end + 1;
 137  * }
 138  * \endcode
 139  *
 140  * @param map the map
 141  * @param start range start
 142  * @param option defines whether surrogates are treated normally,
 143  *               or as having the surrogateValue; usually UCPMAP_RANGE_NORMAL
 144  * @param surrogateValue value for surrogates; ignored if option==UCPMAP_RANGE_NORMAL
 145  * @param filter a pointer to a function that may modify the map data value,
 146  *     or NULL if the values from the map are to be used unmodified
 147  * @param context an opaque pointer that is passed on to the filter function
 148  * @param pValue if not NULL, receives the value that every code point start..end has;
 149  *     may have been modified by filter(context, map value)
 150  *     if that function pointer is not NULL
 151  * @return the range end code point, or -1 if start is not a valid code point
 152  * @draft ICU 63
 153  */
 154 U_CAPI UChar32 U_EXPORT2
 155 ucpmap_getRange(const UCPMap *map, UChar32 start,
 156                 UCPMapRangeOption option, uint32_t surrogateValue,
 157                 UCPMapValueFilter *filter, const void *context, uint32_t *pValue);
 158
 159 U_CDECL_END
 160
 161 #endif  // U_HIDE_DRAFT_API
 162 #endif