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
14U_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 */
33typedef 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 */
44enum 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
85typedef 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 */
98U_CAPI uint32_t U_EXPORT2
99ucpmap_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 */
115typedef uint32_t U_CALLCONV
116UCPMapValueFilter(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 */
154U_CAPI UChar32 U_EXPORT2
155ucpmap_getRange(const UCPMap *map, UChar32 start,
156 UCPMapRangeOption option, uint32_t surrogateValue,
157 UCPMapValueFilter *filter, const void *context, uint32_t *pValue);
158
159U_CDECL_END
160
161#endif // U_HIDE_DRAFT_API
162#endif
163