umutablecptrie.h File Reference

C API: This file defines a mutable Unicode code point trie. More...

#include "unicode/utypes.h"
#include "unicode/ucpmap.h"
#include "unicode/ucptrie.h"
#include "unicode/utf8.h"
#include "unicode/localpointer.h"

Go to the source code of this file.

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef struct UMutableCPTrie	UMutableCPTrie
	Mutable Unicode code point trie.

Functions
U_CAPI UMutableCPTrie *	umutablecptrie_open (uint32_t initialValue, uint32_t errorValue, UErrorCode *pErrorCode)
	Creates a mutable trie that initially maps each Unicode code point to the same value.
U_CAPI UMutableCPTrie *	umutablecptrie_clone (const UMutableCPTrie *other, UErrorCode *pErrorCode)
	Clones a mutable trie.
U_CAPI void	umutablecptrie_close (UMutableCPTrie *trie)
	Closes a mutable trie and releases associated memory.
U_CAPI UMutableCPTrie *	umutablecptrie_fromUCPMap (const UCPMap *map, UErrorCode *pErrorCode)
	Creates a mutable trie with the same contents as the UCPMap.
U_CAPI UMutableCPTrie *	umutablecptrie_fromUCPTrie (const UCPTrie *trie, UErrorCode *pErrorCode)
	Creates a mutable trie with the same contents as the immutable one.
U_CAPI uint32_t	umutablecptrie_get (const UMutableCPTrie *trie, UChar32 c)
	Returns the value for a code point as stored in the trie.
U_CAPI UChar32	umutablecptrie_getRange (const UMutableCPTrie *trie, 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.
U_CAPI void	umutablecptrie_set (UMutableCPTrie *trie, UChar32 c, uint32_t value, UErrorCode *pErrorCode)
	Sets a value for a code point.
U_CAPI void	umutablecptrie_setRange (UMutableCPTrie *trie, UChar32 start, UChar32 end, uint32_t value, UErrorCode *pErrorCode)
	Sets a value for each code point [start..end].
U_CAPI UCPTrie *	umutablecptrie_buildImmutable (UMutableCPTrie *trie, UCPTrieType type, UCPTrieValueWidth valueWidth, UErrorCode *pErrorCode)
	Compacts the data and builds an immutable UCPTrie according to the parameters.

Detailed Description

C API: This file defines a mutable Unicode code point trie.

See also

UCPTrie

UMutableCPTrie

Definition in file umutablecptrie.h.

Typedef Documentation

UMutableCPTrie

typedef struct UMutableCPTrie UMutableCPTrie

Mutable Unicode code point trie.

Fast map from Unicode code points (U+0000..U+10FFFF) to 32-bit integer values. For details see https://icu.unicode.org/design/struct/utrie

Setting values (especially ranges) and lookup is fast. The mutable trie is only somewhat space-efficient. It builds a compacted, immutable UCPTrie.

This trie can be modified while iterating over its contents. For example, it is possible to merge its values with those from another set of ranges (e.g., another mutable or immutable trie): Iterate over those source ranges; for each of them iterate over this trie; add the source value into the value of each trie range.

See also

UCPTrie

umutablecptrie_buildImmutable

Stable:

ICU 63

Definition at line 49 of file umutablecptrie.h.

Function Documentation

umutablecptrie_buildImmutable()

U_CAPI UCPTrie * umutablecptrie_buildImmutable	(	UMutableCPTrie *	trie,
		UCPTrieType	type,
		UCPTrieValueWidth	valueWidth,
		UErrorCode *	pErrorCode
	)

Compacts the data and builds an immutable UCPTrie according to the parameters.

After this, the mutable trie will be empty.

The mutable trie stores 32-bit values until buildImmutable() is called. If values shorter than 32 bits are to be stored in the immutable trie, then the upper bits are discarded. For example, when the mutable trie contains values 0x81, -0x7f, and 0xa581, and the value width is 8 bits, then each of these is stored as 0x81 and the immutable trie will return that as an unsigned value. (Some implementations may want to make productive temporary use of the upper bits until buildImmutable() discards them.)

Not every possible set of mappings can be built into a UCPTrie, because of limitations resulting from speed and space optimizations. Every Unicode assigned character can be mapped to a unique value. Typical data yields data structures far smaller than the limitations.

It is possible to construct extremely unusual mappings that exceed the data structure limits. In such a case this function will fail with a U_INDEX_OUTOFBOUNDS_ERROR.

Parameters

trie	the trie trie
type	selects the trie type
valueWidth	selects the number of bits in a trie data value; if smaller than 32 bits, then the values stored in the trie will be truncated first
pErrorCode	an in/out ICU UErrorCode

See also

umutablecptrie_fromUCPTrie

Stable:

ICU 63

umutablecptrie_clone()

U_CAPI UMutableCPTrie * umutablecptrie_clone	(	const UMutableCPTrie *	other,
		UErrorCode *	pErrorCode
	)

Clones a mutable trie.

You must umutablecptrie_close() the clone once you are done using it.

Parameters

other	the trie to clone
pErrorCode	an in/out ICU UErrorCode

Returns

the trie clone

Stable:

ICU 63

umutablecptrie_close()

U_CAPI void umutablecptrie_close

(

UMutableCPTrie *

trie

)

Closes a mutable trie and releases associated memory.

Parameters

trie

the trie

Stable:

ICU 63

umutablecptrie_fromUCPMap()

U_CAPI UMutableCPTrie * umutablecptrie_fromUCPMap	(	const UCPMap *	map,
		UErrorCode *	pErrorCode
	)

Creates a mutable trie with the same contents as the UCPMap.

You must umutablecptrie_close() the mutable trie once you are done using it.

Parameters

map	the source map
pErrorCode	an in/out ICU UErrorCode

Returns

the mutable trie

Stable:

ICU 63

umutablecptrie_fromUCPTrie()

U_CAPI UMutableCPTrie * umutablecptrie_fromUCPTrie	(	const UCPTrie *	trie,
		UErrorCode *	pErrorCode
	)

Creates a mutable trie with the same contents as the immutable one.

You must umutablecptrie_close() the mutable trie once you are done using it.

Parameters

trie	the immutable trie
pErrorCode	an in/out ICU UErrorCode

Returns

the mutable trie

Stable:

ICU 63

umutablecptrie_get()

U_CAPI uint32_t umutablecptrie_get	(	const UMutableCPTrie *	trie,
		UChar32	c
	)

Returns the value for a code point as stored in the trie.

Parameters

trie	the trie
c	the code point

Returns

the value

Stable:

ICU 63

umutablecptrie_getRange()

U_CAPI UChar32 umutablecptrie_getRange	(	const UMutableCPTrie *	trie,
		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 trie. (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.)

The trie can be modified between calls to this function.

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.

See the same-signature ucptrie_getRange() for a code sample.

Parameters

trie	the trie
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 trie data value, or NULL if the values from the trie 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, trie 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

umutablecptrie_open()

U_CAPI UMutableCPTrie * umutablecptrie_open	(	uint32_t	initialValue,
		uint32_t	errorValue,
		UErrorCode *	pErrorCode
	)

Creates a mutable trie that initially maps each Unicode code point to the same value.

It uses 32-bit data values until umutablecptrie_buildImmutable() is called. umutablecptrie_buildImmutable() takes a valueWidth parameter which determines the number of bits in the data value in the resulting UCPTrie. You must umutablecptrie_close() the trie once you are done using it.

Parameters

initialValue	the initial value that is set for all code points
errorValue	the value for out-of-range code points and ill-formed UTF-8/16
pErrorCode	an in/out ICU UErrorCode

Returns

the trie

Stable:

ICU 63

umutablecptrie_set()

U_CAPI void umutablecptrie_set	(	UMutableCPTrie *	trie,
		UChar32	c,
		uint32_t	value,
		UErrorCode *	pErrorCode
	)

Sets a value for a code point.

Parameters

trie	the trie
c	the code point
value	the value
pErrorCode	an in/out ICU UErrorCode

Stable:

ICU 63

umutablecptrie_setRange()

U_CAPI void umutablecptrie_setRange	(	UMutableCPTrie *	trie,
		UChar32	start,
		UChar32	end,
		uint32_t	value,
		UErrorCode *	pErrorCode
	)

Sets a value for each code point [start..end].

Faster and more space-efficient than setting the value for each code point separately.

Parameters

trie	the trie
start	the first code point to get the value
end	the last code point to get the value (inclusive)
value	the value
pErrorCode	an in/out ICU UErrorCode

Stable:

ICU 63