"Fossies" - the Fresh Open Source Software Archive

Member "icu/source/common/unicode/umutablecptrie.h" (22 Apr 2020, 8435 Bytes) of package /linux/misc/icu4c-67_1-src.tgz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "umutablecptrie.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes reports: 67rc_vs_67_1 or 66_1_vs_67_1.

    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 /**
   87  * Creates a mutable trie with the same contents as the UCPMap.
   88  * You must umutablecptrie_close() the mutable trie once you are done using it.
   89  *
   90  * @param map the source map
   91  * @param pErrorCode an in/out ICU UErrorCode
   92  * @return the mutable trie
   93  * @stable ICU 63
   94  */
   95 U_CAPI UMutableCPTrie * U_EXPORT2
   96 umutablecptrie_fromUCPMap(const UCPMap *map, UErrorCode *pErrorCode);
   97 
   98 /**
   99  * Creates a mutable trie with the same contents as the immutable one.
  100  * You must umutablecptrie_close() the mutable trie once you are done using it.
  101  *
  102  * @param trie the immutable trie
  103  * @param pErrorCode an in/out ICU UErrorCode
  104  * @return the mutable trie
  105  * @stable ICU 63
  106  */
  107 U_CAPI UMutableCPTrie * U_EXPORT2
  108 umutablecptrie_fromUCPTrie(const UCPTrie *trie, UErrorCode *pErrorCode);
  109 
  110 /**
  111  * Returns the value for a code point as stored in the trie.
  112  *
  113  * @param trie the trie
  114  * @param c the code point
  115  * @return the value
  116  * @stable ICU 63
  117  */
  118 U_CAPI uint32_t U_EXPORT2
  119 umutablecptrie_get(const UMutableCPTrie *trie, UChar32 c);
  120 
  121 /**
  122  * Returns the last code point such that all those from start to there have the same value.
  123  * Can be used to efficiently iterate over all same-value ranges in a trie.
  124  * (This is normally faster than iterating over code points and get()ting each value,
  125  * but much slower than a data structure that stores ranges directly.)
  126  *
  127  * The trie can be modified between calls to this function.
  128  *
  129  * If the UCPMapValueFilter function pointer is not NULL, then
  130  * the value to be delivered is passed through that function, and the return value is the end
  131  * of the range where all values are modified to the same actual value.
  132  * The value is unchanged if that function pointer is NULL.
  133  *
  134  * See the same-signature ucptrie_getRange() for a code sample.
  135  *
  136  * @param trie the trie
  137  * @param start range start
  138  * @param option defines whether surrogates are treated normally,
  139  *               or as having the surrogateValue; usually UCPMAP_RANGE_NORMAL
  140  * @param surrogateValue value for surrogates; ignored if option==UCPMAP_RANGE_NORMAL
  141  * @param filter a pointer to a function that may modify the trie data value,
  142  *     or NULL if the values from the trie are to be used unmodified
  143  * @param context an opaque pointer that is passed on to the filter function
  144  * @param pValue if not NULL, receives the value that every code point start..end has;
  145  *     may have been modified by filter(context, trie value)
  146  *     if that function pointer is not NULL
  147  * @return the range end code point, or -1 if start is not a valid code point
  148  * @stable ICU 63
  149  */
  150 U_CAPI UChar32 U_EXPORT2
  151 umutablecptrie_getRange(const UMutableCPTrie *trie, UChar32 start,
  152                         UCPMapRangeOption option, uint32_t surrogateValue,
  153                         UCPMapValueFilter *filter, const void *context, uint32_t *pValue);
  154 
  155 /**
  156  * Sets a value for a code point.
  157  *
  158  * @param trie the trie
  159  * @param c the code point
  160  * @param value the value
  161  * @param pErrorCode an in/out ICU UErrorCode
  162  * @stable ICU 63
  163  */
  164 U_CAPI void U_EXPORT2
  165 umutablecptrie_set(UMutableCPTrie *trie, UChar32 c, uint32_t value, UErrorCode *pErrorCode);
  166 
  167 /**
  168  * Sets a value for each code point [start..end].
  169  * Faster and more space-efficient than setting the value for each code point separately.
  170  *
  171  * @param trie the trie
  172  * @param start the first code point to get the value
  173  * @param end the last code point to get the value (inclusive)
  174  * @param value the value
  175  * @param pErrorCode an in/out ICU UErrorCode
  176  * @stable ICU 63
  177  */
  178 U_CAPI void U_EXPORT2
  179 umutablecptrie_setRange(UMutableCPTrie *trie,
  180                         UChar32 start, UChar32 end,
  181                         uint32_t value, UErrorCode *pErrorCode);
  182 
  183 /**
  184  * Compacts the data and builds an immutable UCPTrie according to the parameters.
  185  * After this, the mutable trie will be empty.
  186  *
  187  * The mutable trie stores 32-bit values until buildImmutable() is called.
  188  * If values shorter than 32 bits are to be stored in the immutable trie,
  189  * then the upper bits are discarded.
  190  * For example, when the mutable trie contains values 0x81, -0x7f, and 0xa581,
  191  * and the value width is 8 bits, then each of these is stored as 0x81
  192  * and the immutable trie will return that as an unsigned value.
  193  * (Some implementations may want to make productive temporary use of the upper bits
  194  * until buildImmutable() discards them.)
  195  *
  196  * Not every possible set of mappings can be built into a UCPTrie,
  197  * because of limitations resulting from speed and space optimizations.
  198  * Every Unicode assigned character can be mapped to a unique value.
  199  * Typical data yields data structures far smaller than the limitations.
  200  *
  201  * It is possible to construct extremely unusual mappings that exceed the data structure limits.
  202  * In such a case this function will fail with a U_INDEX_OUTOFBOUNDS_ERROR.
  203  *
  204  * @param trie the trie trie
  205  * @param type selects the trie type
  206  * @param valueWidth selects the number of bits in a trie data value; if smaller than 32 bits,
  207  *                   then the values stored in the trie will be truncated first
  208  * @param pErrorCode an in/out ICU UErrorCode
  209  *
  210  * @see umutablecptrie_fromUCPTrie
  211  * @stable ICU 63
  212  */
  213 U_CAPI UCPTrie * U_EXPORT2
  214 umutablecptrie_buildImmutable(UMutableCPTrie *trie, UCPTrieType type, UCPTrieValueWidth valueWidth,
  215                               UErrorCode *pErrorCode);
  216 
  217 U_CDECL_END
  218 
  219 #if U_SHOW_CPLUSPLUS_API
  220 
  221 U_NAMESPACE_BEGIN
  222 
  223 /**
  224  * \class LocalUMutableCPTriePointer
  225  * "Smart pointer" class, closes a UMutableCPTrie via umutablecptrie_close().
  226  * For most methods see the LocalPointerBase base class.
  227  *
  228  * @see LocalPointerBase
  229  * @see LocalPointer
  230  * @stable ICU 63
  231  */
  232 U_DEFINE_LOCAL_OPEN_POINTER(LocalUMutableCPTriePointer, UMutableCPTrie, umutablecptrie_close);
  233 
  234 U_NAMESPACE_END
  235 
  236 #endif
  237 
  238 #endif