Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/umutablecptrie.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 // © 2017 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 // umutablecptrie.h (split out of ucptrie.h)
jpayne@69 5 // created: 2018jan24 Markus W. Scherer
jpayne@69 6
jpayne@69 7 #ifndef __UMUTABLECPTRIE_H__
jpayne@69 8 #define __UMUTABLECPTRIE_H__
jpayne@69 9
jpayne@69 10 #include "unicode/utypes.h"
jpayne@69 11
jpayne@69 12 #include "unicode/localpointer.h"
jpayne@69 13 #include "unicode/ucpmap.h"
jpayne@69 14 #include "unicode/ucptrie.h"
jpayne@69 15 #include "unicode/utf8.h"
jpayne@69 16
jpayne@69 17 U_CDECL_BEGIN
jpayne@69 18
jpayne@69 19 /**
jpayne@69 20 * \file
jpayne@69 21 *
jpayne@69 22 * This file defines a mutable Unicode code point trie.
jpayne@69 23 *
jpayne@69 24 * @see UCPTrie
jpayne@69 25 * @see UMutableCPTrie
jpayne@69 26 */
jpayne@69 27
jpayne@69 28 /**
jpayne@69 29 * Mutable Unicode code point trie.
jpayne@69 30 * Fast map from Unicode code points (U+0000..U+10FFFF) to 32-bit integer values.
jpayne@69 31 * For details see http://site.icu-project.org/design/struct/utrie
jpayne@69 32 *
jpayne@69 33 * Setting values (especially ranges) and lookup is fast.
jpayne@69 34 * The mutable trie is only somewhat space-efficient.
jpayne@69 35 * It builds a compacted, immutable UCPTrie.
jpayne@69 36 *
jpayne@69 37 * This trie can be modified while iterating over its contents.
jpayne@69 38 * For example, it is possible to merge its values with those from another
jpayne@69 39 * set of ranges (e.g., another mutable or immutable trie):
jpayne@69 40 * Iterate over those source ranges; for each of them iterate over this trie;
jpayne@69 41 * add the source value into the value of each trie range.
jpayne@69 42 *
jpayne@69 43 * @see UCPTrie
jpayne@69 44 * @see umutablecptrie_buildImmutable
jpayne@69 45 * @stable ICU 63
jpayne@69 46 */
jpayne@69 47 typedef struct UMutableCPTrie UMutableCPTrie;
jpayne@69 48
jpayne@69 49 /**
jpayne@69 50 * Creates a mutable trie that initially maps each Unicode code point to the same value.
jpayne@69 51 * It uses 32-bit data values until umutablecptrie_buildImmutable() is called.
jpayne@69 52 * umutablecptrie_buildImmutable() takes a valueWidth parameter which
jpayne@69 53 * determines the number of bits in the data value in the resulting UCPTrie.
jpayne@69 54 * You must umutablecptrie_close() the trie once you are done using it.
jpayne@69 55 *
jpayne@69 56 * @param initialValue the initial value that is set for all code points
jpayne@69 57 * @param errorValue the value for out-of-range code points and ill-formed UTF-8/16
jpayne@69 58 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 59 * @return the trie
jpayne@69 60 * @stable ICU 63
jpayne@69 61 */
jpayne@69 62 U_CAPI UMutableCPTrie * U_EXPORT2
jpayne@69 63 umutablecptrie_open(uint32_t initialValue, uint32_t errorValue, UErrorCode *pErrorCode);
jpayne@69 64
jpayne@69 65 /**
jpayne@69 66 * Clones a mutable trie.
jpayne@69 67 * You must umutablecptrie_close() the clone once you are done using it.
jpayne@69 68 *
jpayne@69 69 * @param other the trie to clone
jpayne@69 70 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 71 * @return the trie clone
jpayne@69 72 * @stable ICU 63
jpayne@69 73 */
jpayne@69 74 U_CAPI UMutableCPTrie * U_EXPORT2
jpayne@69 75 umutablecptrie_clone(const UMutableCPTrie *other, UErrorCode *pErrorCode);
jpayne@69 76
jpayne@69 77 /**
jpayne@69 78 * Closes a mutable trie and releases associated memory.
jpayne@69 79 *
jpayne@69 80 * @param trie the trie
jpayne@69 81 * @stable ICU 63
jpayne@69 82 */
jpayne@69 83 U_CAPI void U_EXPORT2
jpayne@69 84 umutablecptrie_close(UMutableCPTrie *trie);
jpayne@69 85
jpayne@69 86 /**
jpayne@69 87 * Creates a mutable trie with the same contents as the UCPMap.
jpayne@69 88 * You must umutablecptrie_close() the mutable trie once you are done using it.
jpayne@69 89 *
jpayne@69 90 * @param map the source map
jpayne@69 91 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 92 * @return the mutable trie
jpayne@69 93 * @stable ICU 63
jpayne@69 94 */
jpayne@69 95 U_CAPI UMutableCPTrie * U_EXPORT2
jpayne@69 96 umutablecptrie_fromUCPMap(const UCPMap *map, UErrorCode *pErrorCode);
jpayne@69 97
jpayne@69 98 /**
jpayne@69 99 * Creates a mutable trie with the same contents as the immutable one.
jpayne@69 100 * You must umutablecptrie_close() the mutable trie once you are done using it.
jpayne@69 101 *
jpayne@69 102 * @param trie the immutable trie
jpayne@69 103 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 104 * @return the mutable trie
jpayne@69 105 * @stable ICU 63
jpayne@69 106 */
jpayne@69 107 U_CAPI UMutableCPTrie * U_EXPORT2
jpayne@69 108 umutablecptrie_fromUCPTrie(const UCPTrie *trie, UErrorCode *pErrorCode);
jpayne@69 109
jpayne@69 110 /**
jpayne@69 111 * Returns the value for a code point as stored in the trie.
jpayne@69 112 *
jpayne@69 113 * @param trie the trie
jpayne@69 114 * @param c the code point
jpayne@69 115 * @return the value
jpayne@69 116 * @stable ICU 63
jpayne@69 117 */
jpayne@69 118 U_CAPI uint32_t U_EXPORT2
jpayne@69 119 umutablecptrie_get(const UMutableCPTrie *trie, UChar32 c);
jpayne@69 120
jpayne@69 121 /**
jpayne@69 122 * Returns the last code point such that all those from start to there have the same value.
jpayne@69 123 * Can be used to efficiently iterate over all same-value ranges in a trie.
jpayne@69 124 * (This is normally faster than iterating over code points and get()ting each value,
jpayne@69 125 * but much slower than a data structure that stores ranges directly.)
jpayne@69 126 *
jpayne@69 127 * The trie can be modified between calls to this function.
jpayne@69 128 *
jpayne@69 129 * If the UCPMapValueFilter function pointer is not NULL, then
jpayne@69 130 * the value to be delivered is passed through that function, and the return value is the end
jpayne@69 131 * of the range where all values are modified to the same actual value.
jpayne@69 132 * The value is unchanged if that function pointer is NULL.
jpayne@69 133 *
jpayne@69 134 * See the same-signature ucptrie_getRange() for a code sample.
jpayne@69 135 *
jpayne@69 136 * @param trie the trie
jpayne@69 137 * @param start range start
jpayne@69 138 * @param option defines whether surrogates are treated normally,
jpayne@69 139 * or as having the surrogateValue; usually UCPMAP_RANGE_NORMAL
jpayne@69 140 * @param surrogateValue value for surrogates; ignored if option==UCPMAP_RANGE_NORMAL
jpayne@69 141 * @param filter a pointer to a function that may modify the trie data value,
jpayne@69 142 * or NULL if the values from the trie are to be used unmodified
jpayne@69 143 * @param context an opaque pointer that is passed on to the filter function
jpayne@69 144 * @param pValue if not NULL, receives the value that every code point start..end has;
jpayne@69 145 * may have been modified by filter(context, trie value)
jpayne@69 146 * if that function pointer is not NULL
jpayne@69 147 * @return the range end code point, or -1 if start is not a valid code point
jpayne@69 148 * @stable ICU 63
jpayne@69 149 */
jpayne@69 150 U_CAPI UChar32 U_EXPORT2
jpayne@69 151 umutablecptrie_getRange(const UMutableCPTrie *trie, UChar32 start,
jpayne@69 152 UCPMapRangeOption option, uint32_t surrogateValue,
jpayne@69 153 UCPMapValueFilter *filter, const void *context, uint32_t *pValue);
jpayne@69 154
jpayne@69 155 /**
jpayne@69 156 * Sets a value for a code point.
jpayne@69 157 *
jpayne@69 158 * @param trie the trie
jpayne@69 159 * @param c the code point
jpayne@69 160 * @param value the value
jpayne@69 161 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 162 * @stable ICU 63
jpayne@69 163 */
jpayne@69 164 U_CAPI void U_EXPORT2
jpayne@69 165 umutablecptrie_set(UMutableCPTrie *trie, UChar32 c, uint32_t value, UErrorCode *pErrorCode);
jpayne@69 166
jpayne@69 167 /**
jpayne@69 168 * Sets a value for each code point [start..end].
jpayne@69 169 * Faster and more space-efficient than setting the value for each code point separately.
jpayne@69 170 *
jpayne@69 171 * @param trie the trie
jpayne@69 172 * @param start the first code point to get the value
jpayne@69 173 * @param end the last code point to get the value (inclusive)
jpayne@69 174 * @param value the value
jpayne@69 175 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 176 * @stable ICU 63
jpayne@69 177 */
jpayne@69 178 U_CAPI void U_EXPORT2
jpayne@69 179 umutablecptrie_setRange(UMutableCPTrie *trie,
jpayne@69 180 UChar32 start, UChar32 end,
jpayne@69 181 uint32_t value, UErrorCode *pErrorCode);
jpayne@69 182
jpayne@69 183 /**
jpayne@69 184 * Compacts the data and builds an immutable UCPTrie according to the parameters.
jpayne@69 185 * After this, the mutable trie will be empty.
jpayne@69 186 *
jpayne@69 187 * The mutable trie stores 32-bit values until buildImmutable() is called.
jpayne@69 188 * If values shorter than 32 bits are to be stored in the immutable trie,
jpayne@69 189 * then the upper bits are discarded.
jpayne@69 190 * For example, when the mutable trie contains values 0x81, -0x7f, and 0xa581,
jpayne@69 191 * and the value width is 8 bits, then each of these is stored as 0x81
jpayne@69 192 * and the immutable trie will return that as an unsigned value.
jpayne@69 193 * (Some implementations may want to make productive temporary use of the upper bits
jpayne@69 194 * until buildImmutable() discards them.)
jpayne@69 195 *
jpayne@69 196 * Not every possible set of mappings can be built into a UCPTrie,
jpayne@69 197 * because of limitations resulting from speed and space optimizations.
jpayne@69 198 * Every Unicode assigned character can be mapped to a unique value.
jpayne@69 199 * Typical data yields data structures far smaller than the limitations.
jpayne@69 200 *
jpayne@69 201 * It is possible to construct extremely unusual mappings that exceed the data structure limits.
jpayne@69 202 * In such a case this function will fail with a U_INDEX_OUTOFBOUNDS_ERROR.
jpayne@69 203 *
jpayne@69 204 * @param trie the trie trie
jpayne@69 205 * @param type selects the trie type
jpayne@69 206 * @param valueWidth selects the number of bits in a trie data value; if smaller than 32 bits,
jpayne@69 207 * then the values stored in the trie will be truncated first
jpayne@69 208 * @param pErrorCode an in/out ICU UErrorCode
jpayne@69 209 *
jpayne@69 210 * @see umutablecptrie_fromUCPTrie
jpayne@69 211 * @stable ICU 63
jpayne@69 212 */
jpayne@69 213 U_CAPI UCPTrie * U_EXPORT2
jpayne@69 214 umutablecptrie_buildImmutable(UMutableCPTrie *trie, UCPTrieType type, UCPTrieValueWidth valueWidth,
jpayne@69 215 UErrorCode *pErrorCode);
jpayne@69 216
jpayne@69 217 U_CDECL_END
jpayne@69 218
jpayne@69 219 #if U_SHOW_CPLUSPLUS_API
jpayne@69 220
jpayne@69 221 U_NAMESPACE_BEGIN
jpayne@69 222
jpayne@69 223 /**
jpayne@69 224 * \class LocalUMutableCPTriePointer
jpayne@69 225 * "Smart pointer" class, closes a UMutableCPTrie via umutablecptrie_close().
jpayne@69 226 * For most methods see the LocalPointerBase base class.
jpayne@69 227 *
jpayne@69 228 * @see LocalPointerBase
jpayne@69 229 * @see LocalPointer
jpayne@69 230 * @stable ICU 63
jpayne@69 231 */
jpayne@69 232 U_DEFINE_LOCAL_OPEN_POINTER(LocalUMutableCPTriePointer, UMutableCPTrie, umutablecptrie_close);
jpayne@69 233
jpayne@69 234 U_NAMESPACE_END
jpayne@69 235
jpayne@69 236 #endif
jpayne@69 237
jpayne@69 238 #endif