include/unicode/ucpmap.h

0001 // © 2018 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003
0004 // ucpmap.h
0005 // created: 2018sep03 Markus W. Scherer
0006
0007 #ifndef __UCPMAP_H__
0008 #define __UCPMAP_H__
0009
0010 #include "unicode/utypes.h"
0011
0012 U_CDECL_BEGIN
0013
0014 /**
0015  * \file
0016  * \brief C API: This file defines an abstract map from Unicode code points to integer values.
0017  *
0018  * @see UCPMap
0019  * @see UCPTrie
0020  * @see UMutableCPTrie
0021  */
0022
0023 /**
0024  * Abstract map from Unicode code points (U+0000..U+10FFFF) to integer values.
0025  *
0026  * @see UCPTrie
0027  * @see UMutableCPTrie
0028  * @stable ICU 63
0029  */
0030 typedef struct UCPMap UCPMap;
0031
0032 /**
0033  * Selectors for how ucpmap_getRange() etc. should report value ranges overlapping with surrogates.
0034  * Most users should use UCPMAP_RANGE_NORMAL.
0035  *
0036  * @see ucpmap_getRange
0037  * @see ucptrie_getRange
0038  * @see umutablecptrie_getRange
0039  * @stable ICU 63
0040  */
0041 enum UCPMapRangeOption {
0042     /**
0043      * ucpmap_getRange() enumerates all same-value ranges as stored in the map.
0044      * Most users should use this option.
0045      * @stable ICU 63
0046      */
0047     UCPMAP_RANGE_NORMAL,
0048     /**
0049      * ucpmap_getRange() enumerates all same-value ranges as stored in the map,
0050      * except that lead surrogates (U+D800..U+DBFF) are treated as having the
0051      * surrogateValue, which is passed to getRange() as a separate parameter.
0052      * The surrogateValue is not transformed via filter().
0053      * See U_IS_LEAD(c).
0054      *
0055      * Most users should use UCPMAP_RANGE_NORMAL instead.
0056      *
0057      * This option is useful for maps that map surrogate code *units* to
0058      * special values optimized for UTF-16 string processing
0059      * or for special error behavior for unpaired surrogates,
0060      * but those values are not to be associated with the lead surrogate code *points*.
0061      * @stable ICU 63
0062      */
0063     UCPMAP_RANGE_FIXED_LEAD_SURROGATES,
0064     /**
0065      * ucpmap_getRange() enumerates all same-value ranges as stored in the map,
0066      * except that all surrogates (U+D800..U+DFFF) are treated as having the
0067      * surrogateValue, which is passed to getRange() as a separate parameter.
0068      * The surrogateValue is not transformed via filter().
0069      * See U_IS_SURROGATE(c).
0070      *
0071      * Most users should use UCPMAP_RANGE_NORMAL instead.
0072      *
0073      * This option is useful for maps that map surrogate code *units* to
0074      * special values optimized for UTF-16 string processing
0075      * or for special error behavior for unpaired surrogates,
0076      * but those values are not to be associated with the lead surrogate code *points*.
0077      * @stable ICU 63
0078      */
0079     UCPMAP_RANGE_FIXED_ALL_SURROGATES
0080 };
0081 #ifndef U_IN_DOXYGEN
0082 typedef enum UCPMapRangeOption UCPMapRangeOption;
0083 #endif
0084
0085 /**
0086  * Returns the value for a code point as stored in the map, with range checking.
0087  * Returns an implementation-defined error value if c is not in the range 0..U+10FFFF.
0088  *
0089  * @param map the map
0090  * @param c the code point
0091  * @return the map value,
0092  *         or an implementation-defined error value if the code point is not in the range 0..U+10FFFF
0093  * @stable ICU 63
0094  */
0095 U_CAPI uint32_t U_EXPORT2
0096 ucpmap_get(const UCPMap *map, UChar32 c);
0097
0098 /**
0099  * Callback function type: Modifies a map value.
0100  * Optionally called by ucpmap_getRange()/ucptrie_getRange()/umutablecptrie_getRange().
0101  * The modified value will be returned by the getRange function.
0102  *
0103  * Can be used to ignore some of the value bits,
0104  * make a filter for one of several values,
0105  * return a value index computed from the map value, etc.
0106  *
0107  * @param context an opaque pointer, as passed into the getRange function
0108  * @param value a value from the map
0109  * @return the modified value
0110  * @stable ICU 63
0111  */
0112 typedef uint32_t U_CALLCONV
0113 UCPMapValueFilter(const void *context, uint32_t value);
0114
0115 /**
0116  * Returns the last code point such that all those from start to there have the same value.
0117  * Can be used to efficiently iterate over all same-value ranges in a map.
0118  * (This is normally faster than iterating over code points and get()ting each value,
0119  * but much slower than a data structure that stores ranges directly.)
0120  *
0121  * If the UCPMapValueFilter function pointer is not NULL, then
0122  * the value to be delivered is passed through that function, and the return value is the end
0123  * of the range where all values are modified to the same actual value.
0124  * The value is unchanged if that function pointer is NULL.
0125  *
0126  * Example:
0127  * \code
0128  * UChar32 start = 0, end;
0129  * uint32_t value;
0130  * while ((end = ucpmap_getRange(map, start, UCPMAP_RANGE_NORMAL, 0,
0131  *                               NULL, NULL, &value)) >= 0) {
0132  *     // Work with the range start..end and its value.
0133  *     start = end + 1;
0134  * }
0135  * \endcode
0136  *
0137  * @param map the map
0138  * @param start range start
0139  * @param option defines whether surrogates are treated normally,
0140  *               or as having the surrogateValue; usually UCPMAP_RANGE_NORMAL
0141  * @param surrogateValue value for surrogates; ignored if option==UCPMAP_RANGE_NORMAL
0142  * @param filter a pointer to a function that may modify the map data value,
0143  *     or NULL if the values from the map are to be used unmodified
0144  * @param context an opaque pointer that is passed on to the filter function
0145  * @param pValue if not NULL, receives the value that every code point start..end has;
0146  *     may have been modified by filter(context, map value)
0147  *     if that function pointer is not NULL
0148  * @return the range end code point, or -1 if start is not a valid code point
0149  * @stable ICU 63
0150  */
0151 U_CAPI UChar32 U_EXPORT2
0152 ucpmap_getRange(const UCPMap *map, UChar32 start,
0153                 UCPMapRangeOption option, uint32_t surrogateValue,
0154                 UCPMapValueFilter *filter, const void *context, uint32_t *pValue);
0155
0156 U_CDECL_END
0157
0158 #endif