Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ucpmap.h @ 69:33d812a61356

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