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 163