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 U_CDECL_BEGIN
13 
14 /**
15  * \file
16  *
17  * This file defines an abstract map from Unicode code points to integer values.
18  *
19  * @see UCPMap
20  * @see UCPTrie
21  * @see UMutableCPTrie
22  */
23 
24 /**
25  * Abstract map from Unicode code points (U+0000..U+10FFFF) to integer values.
26  *
27  * @see UCPTrie
28  * @see UMutableCPTrie
29  * @stable ICU 63
30  */
31 typedef struct UCPMap UCPMap;
32 
33 /**
34  * Selectors for how ucpmap_getRange() etc. should report value ranges overlapping with surrogates.
35  * Most users should use UCPMAP_RANGE_NORMAL.
36  *
37  * @see ucpmap_getRange
38  * @see ucptrie_getRange
39  * @see umutablecptrie_getRange
40  * @stable ICU 63
41  */
42 enum UCPMapRangeOption {
43     /**
44      * ucpmap_getRange() enumerates all same-value ranges as stored in the map.
45      * Most users should use this option.
46      * @stable ICU 63
47      */
48     UCPMAP_RANGE_NORMAL,
49     /**
50      * ucpmap_getRange() enumerates all same-value ranges as stored in the map,
51      * except that lead surrogates (U+D800..U+DBFF) are treated as having the
52      * surrogateValue, which is passed to getRange() as a separate parameter.
53      * The surrogateValue is not transformed via filter().
54      * See U_IS_LEAD(c).
55      *
56      * Most users should use UCPMAP_RANGE_NORMAL instead.
57      *
58      * This option is useful for maps that map surrogate code *units* to
59      * special values optimized for UTF-16 string processing
60      * or for special error behavior for unpaired surrogates,
61      * but those values are not to be associated with the lead surrogate code *points*.
62      * @stable ICU 63
63      */
64     UCPMAP_RANGE_FIXED_LEAD_SURROGATES,
65     /**
66      * ucpmap_getRange() enumerates all same-value ranges as stored in the map,
67      * except that all surrogates (U+D800..U+DFFF) are treated as having the
68      * surrogateValue, which is passed to getRange() as a separate parameter.
69      * The surrogateValue is not transformed via filter().
70      * See U_IS_SURROGATE(c).
71      *
72      * Most users should use UCPMAP_RANGE_NORMAL instead.
73      *
74      * This option is useful for maps that map surrogate code *units* to
75      * special values optimized for UTF-16 string processing
76      * or for special error behavior for unpaired surrogates,
77      * but those values are not to be associated with the lead surrogate code *points*.
78      * @stable ICU 63
79      */
80     UCPMAP_RANGE_FIXED_ALL_SURROGATES
81 };
82 #ifndef U_IN_DOXYGEN
83 typedef enum UCPMapRangeOption UCPMapRangeOption;
84 #endif
85 
86 
87 
88 /**
89  * Callback function type: Modifies a map value.
90  * Optionally called by ucpmap_getRange()/ucptrie_getRange()/umutablecptrie_getRange().
91  * The modified value will be returned by the getRange function.
92  *
93  * Can be used to ignore some of the value bits,
94  * make a filter for one of several values,
95  * return a value index computed from the map value, etc.
96  *
97  * @param context an opaque pointer, as passed into the getRange function
98  * @param value a value from the map
99  * @return the modified value
100  * @stable ICU 63
101  */
102 typedef uint32_t U_CALLCONV
103 UCPMapValueFilter(const void *context, uint32_t value);
104 
105 
106 
107 U_CDECL_END
108 
109 #endif
110