icuSources/common/unicode/umutablecptrie.h

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