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