ICU 74.2: common/unicode/ucpmap.h File Reference

ICU 74.2 74.2

Typedefs | Enumerations | Functions
ucpmap.h File Reference

C API: This file defines an abstract map from Unicode code points to integer values. More...

`#include "unicode/utypes.h"`

Go to the source code of this file.

## Typedefs
typedef struct UCPMap | UCPMap
| Abstract map from Unicode code points (U+0000..U+10FFFF) to integer values.
typedef uint32_t | UCPMapValueFilter(const void *context, uint32_t value)
| Callback function type: Modifies a map value.

## Enumerations
enum | UCPMapRangeOption { UCPMAP_RANGE_NORMAL , UCPMAP_RANGE_FIXED_LEAD_SURROGATES , UCPMAP_RANGE_FIXED_ALL_SURROGATES }
| Selectors for how ucpmap_getRange() etc. More...

## Functions
U_CAPI uint32_t | ucpmap_get (const UCPMap *map, UChar32 c)
| Returns the value for a code point as stored in the map, with range checking.
U_CAPI UChar32 | ucpmap_getRange (const UCPMap *map, UChar32 start, UCPMapRangeOption option, uint32_t surrogateValue, UCPMapValueFilter *filter, const void *context, uint32_t *pValue)
| Returns the last code point such that all those from start to there have the same value.

## Detailed Description

C API: This file defines an abstract map from Unicode code points to integer values.

See also
  UCPMap
  UCPTrie
  UMutableCPTrie

Definition in file ucpmap.h.

## Typedef Documentation

## ◆ UCPMap

typedef struct UCPMap UCPMap

Abstract map from Unicode code points (U+0000..U+10FFFF) to integer values.

See also
  UCPTrie
  UMutableCPTrie

Stable:
  ICU 63

Definition at line 30 of file ucpmap.h.

## ◆ UCPMapValueFilter

typedef uint32_t UCPMapValueFilter(const void *context, uint32_t value)

Callback function type: Modifies a map value.

Optionally called by ucpmap_getRange()/ucptrie_getRange()/umutablecptrie_getRange(). The modified value will be returned by the getRange function.

Can be used to ignore some of the value bits, make a filter for one of several values, return a value index computed from the map value, etc.

Parameters

  context | an opaque pointer, as passed into the getRange function
  value | a value from the map

Returns
  the modified value

Stable:
  ICU 63

Definition at line 113 of file ucpmap.h.

## Enumeration Type Documentation

## ◆ UCPMapRangeOption

enum UCPMapRangeOption

Selectors for how ucpmap_getRange() etc.

should report value ranges overlapping with surrogates. Most users should use UCPMAP_RANGE_NORMAL.

See also
  ucpmap_getRange
  ucptrie_getRange
  umutablecptrie_getRange

Stable:
  ICU 63

Enumerator
UCPMAP_RANGE_NORMAL | ucpmap_getRange() enumerates all same-value ranges as stored in the map. Most users should use this option. Stable: ICU 63
UCPMAP_RANGE_FIXED_LEAD_SURROGATES | ucpmap_getRange() enumerates all same-value ranges as stored in the map, except that lead surrogates (U+D800..U+DBFF) are treated as having the surrogateValue, which is passed to getRange() as a separate parameter. The surrogateValue is not transformed via filter(). See U_IS_LEAD(c). Most users should use UCPMAP_RANGE_NORMAL instead. This option is useful for maps that map surrogate code units to special values optimized for UTF-16 string processing or for special error behavior for unpaired surrogates, but those values are not to be associated with the lead surrogate code points. Stable: ICU 63
UCPMAP_RANGE_FIXED_ALL_SURROGATES | ucpmap_getRange() enumerates all same-value ranges as stored in the map, except that all surrogates (U+D800..U+DFFF) are treated as having the surrogateValue, which is passed to getRange() as a separate parameter. The surrogateValue is not transformed via filter(). See U_IS_SURROGATE(c). Most users should use UCPMAP_RANGE_NORMAL instead. This option is useful for maps that map surrogate code units to special values optimized for UTF-16 string processing or for special error behavior for unpaired surrogates, but those values are not to be associated with the lead surrogate code points. Stable: ICU 63

Definition at line 41 of file ucpmap.h.

## Function Documentation

## ◆ ucpmap_get()

U_CAPI uint32_t ucpmap_get | ( | const UCPMap * | map,
|  | UChar32 | c
| ) |  |

Returns the value for a code point as stored in the map, with range checking.

Returns an implementation-defined error value if c is not in the range 0..U+10FFFF.

Parameters

  map | the map
  c | the code point

Returns
  the map value, or an implementation-defined error value if the code point is not in the range 0..U+10FFFF

Stable:
  ICU 63

## ◆ ucpmap_getRange()

U_CAPI UChar32 ucpmap_getRange | ( | const UCPMap * | map,
|  | UChar32 | start,
|  | UCPMapRangeOption | option,
|  | uint32_t | surrogateValue,
|  | UCPMapValueFilter * | filter,
|  | const void * | context,
|  | uint32_t * | pValue
| ) |  |

Returns the last code point such that all those from start to there have the same value.

Can be used to efficiently iterate over all same-value ranges in a map. (This is normally faster than iterating over code points and get()ting each value, but much slower than a data structure that stores ranges directly.)

If the UCPMapValueFilter function pointer is not NULL, then the value to be delivered is passed through that function, and the return value is the end of the range where all values are modified to the same actual value. The value is unchanged if that function pointer is NULL.

Example:

UChar32 start = 0, end;
uint32_t value;
while ((end = ucpmap_getRange(map, start, UCPMAP_RANGE_NORMAL, 0,
NULL, NULL, &value)) >= 0) {
// Work with the range start..end and its value.
start = end + 1;
}
ucpmap_getRange
U_CAPI UChar32 ucpmap_getRange(const UCPMap *map, UChar32 start, UCPMapRangeOption option, uint32_t surrogateValue, UCPMapValueFilter *filter, const void *context, uint32_t *pValue)
Returns the last code point such that all those from start to there have the same value.
UCPMAP_RANGE_NORMAL
@ UCPMAP_RANGE_NORMAL
ucpmap_getRange() enumerates all same-value ranges as stored in the map.
Definition ucpmap.h:47
UChar32
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition umachine.h:435
NULL
#define NULL
Define NULL if necessary, to nullptr for C++ and to ((void *)0) for C.
Definition utypes.h:188

Parameters

  map | the map
  start | range start
  option | defines whether surrogates are treated normally, or as having the surrogateValue; usually UCPMAP_RANGE_NORMAL
  surrogateValue | value for surrogates; ignored if option==UCPMAP_RANGE_NORMAL
  filter | a pointer to a function that may modify the map data value, or NULL if the values from the map are to be used unmodified
  context | an opaque pointer that is passed on to the filter function
  pValue | if not NULL, receives the value that every code point start..end has; may have been modified by filter(context, map value) if that function pointer is not NULL

Returns
  the range end code point, or -1 if start is not a valid code point

Stable:
  ICU 63