Struct icu_collections::codepointtrie::CodePointTrie

pub struct CodePointTrie<'trie, T: TrieValue> {
    pub(crate) header: CodePointTrieHeader,
    pub(crate) index: ZeroVec<'trie, u16>,
    pub(crate) data: ZeroVec<'trie, T>,
    pub(crate) error_value: T,
}

This struct represents a de-serialized CodePointTrie that was exported from ICU binary data.

For more information:

• ICU Site design doc
• ICU User Guide section on Properties lookup

Fields

header: CodePointTrieHeader

index: ZeroVec<'trie, u16>

data: ZeroVec<'trie, T>

error_value: T

Implementations

impl<'trie, T: TrieValue> CodePointTrie<'trie, T>

pub fn try_new( header: CodePointTrieHeader, index: ZeroVec<'trie, u16>, data: ZeroVec<'trie, T>, ) -> Result<CodePointTrie<'trie, T>, Error>

Returns a new CodePointTrie backed by borrowed data for the index array and data array, whose data values have width W.

fn trie_error_val_index(&self) -> u32

Returns the position in the data array containing the trie’s stored error value.

fn internal_small_index(&self, code_point: u32) -> u32

fn small_index(&self, code_point: u32) -> u32

Returns the position in the data array for the given code point, where this code point is at or above the fast limit associated for the trie_type. We will refer to that limit as “fastMax” here.

A lookup of the value in the code point trie for a code point in the code point space range [fastMax, high_start) will be a 4-step lookup: 3 lookups in the index array and one lookup in the data array. Lookups for code points in the range [high_start, CODE_POINT_MAX] are short-circuited to be a single lookup, see CodePointTrieHeader::high_start.

fn fast_index(&self, code_point: u32) -> u32

Returns the position in the data array for the given code point, where this code point is below the fast limit associated for the trie type. We will refer to that limit as “fastMax” here.

A lookup of the value in the code point trie for a code point in the code point space range [0, fastMax) will be a 2-step lookup: 1 lookup in the index array and one lookup in the data array. By design, for trie type T, there is an element allocated in the index array for each block of code points in [0, fastMax), which in turn guarantees that those code points are represented and only need 1 lookup.

pub fn get32(&self, code_point: u32) -> T

Returns the value that is associated with code_point in this CodePointTrie.

Examples

use icu::collections::codepointtrie::planes;
let trie = planes::get_planes_trie();

assert_eq!(0, trie.get32(0x41)); // 'A' as u32
assert_eq!(0, trie.get32(0x13E0)); // 'Ꮰ' as u32
assert_eq!(1, trie.get32(0x10044)); // '𐁄' as u32

pub fn get(&self, c: char) -> T

Returns the value that is associated with char in this CodePointTrie.

Examples

use icu::collections::codepointtrie::planes;
let trie = planes::get_planes_trie();

assert_eq!(0, trie.get('A')); // 'A' as u32
assert_eq!(0, trie.get('Ꮰ')); // 'Ꮰ' as u32
assert_eq!(1, trie.get('𐁄')); // '𐁄' as u32

pub fn get32_ule(&self, code_point: u32) -> Option<&T::ULE>

Returns a reference to the ULE of the value that is associated with code_point in this CodePointTrie.

Examples

use icu::collections::codepointtrie::planes;
let trie = planes::get_planes_trie();

assert_eq!(Some(&0), trie.get32_ule(0x41)); // 'A' as u32
assert_eq!(Some(&0), trie.get32_ule(0x13E0)); // 'Ꮰ' as u32
assert_eq!(Some(&1), trie.get32_ule(0x10044)); // '𐁄' as u32

pub fn try_into_converted<P>( self, ) -> Result<CodePointTrie<'trie, P>, ZeroVecError>

where P: TrieValue,

Converts the CodePointTrie into one that returns another type of the same size.

Borrowed data remains borrowed, and owned data remains owned.

If the old and new types are not the same size, use CodePointTrie::try_alloc_map_value.

Panics

Panics if T and P are different sizes.

More specifically, panics if ZeroVec::try_into_converted() panics when converting ZeroVec<T> into ZeroVec<P>, which happens if T::ULE and P::ULE differ in size.

Examples

use icu::collections::codepointtrie::planes;
use icu::collections::codepointtrie::CodePointTrie;

let planes_trie_u8: CodePointTrie<u8> = planes::get_planes_trie();
let planes_trie_i8: CodePointTrie<i8> =
    planes_trie_u8.try_into_converted().expect("infallible");

assert_eq!(planes_trie_i8.get32(0x30000), 3);

pub fn try_alloc_map_value<P, E>( &self, f: impl FnMut(T) -> Result<P, E>, ) -> Result<CodePointTrie<'trie, P>, E>

where P: TrieValue,

Maps the CodePointTrie into one that returns a different type.

This function returns owned data.

If the old and new types are the same size, use the more efficient CodePointTrie::try_into_converted.

Examples

use icu::collections::codepointtrie::planes;
use icu::collections::codepointtrie::CodePointTrie;

let planes_trie_u8: CodePointTrie<u8> = planes::get_planes_trie();
let planes_trie_u16: CodePointTrie<u16> = planes_trie_u8
    .try_alloc_map_value(TryFrom::try_from)
    .expect("infallible");

assert_eq!(planes_trie_u16.get32(0x30000), 3);

pub fn get_range(&self, start: u32) -> Option<CodePointMapRange<T>>

Returns a CodePointMapRange struct which represents a range of code points associated with the same trie value. The returned range will be the longest stretch of consecutive code points starting at start that share this value.

This method is designed to use the internal details of the structure of CodePointTrie to be optimally efficient. This will outperform a naive approach that just uses CodePointTrie::get().

This method provides lower-level functionality that can be used in the implementation of other methods that are more convenient to the user. To obtain an optimal partition of the code point space for this trie resulting in the fewest number of ranges, see CodePointTrie::iter_ranges().

Examples

use icu::collections::codepointtrie::planes;

let trie = planes::get_planes_trie();

const CODE_POINT_MAX: u32 = 0x10ffff;
let start = 0x1_0000;
let exp_end = 0x1_ffff;

let start_val = trie.get32(start);
assert_eq!(trie.get32(exp_end), start_val);
assert_ne!(trie.get32(exp_end + 1), start_val);

use icu::collections::codepointtrie::CodePointMapRange;

let cpm_range: CodePointMapRange<u8> = trie.get_range(start).unwrap();

assert_eq!(cpm_range.range.start(), &start);
assert_eq!(cpm_range.range.end(), &exp_end);
assert_eq!(cpm_range.value, start_val);

// `start` can be any code point, whether or not it lies on the boundary
// of a maximally large range that still contains `start`

let submaximal_1_start = start + 0x1234;
let submaximal_1 = trie.get_range(submaximal_1_start).unwrap();
assert_eq!(submaximal_1.range.start(), &0x1_1234);
assert_eq!(submaximal_1.range.end(), &0x1_ffff);
assert_eq!(submaximal_1.value, start_val);

let submaximal_2_start = start + 0xffff;
let submaximal_2 = trie.get_range(submaximal_2_start).unwrap();
assert_eq!(submaximal_2.range.start(), &0x1_ffff);
assert_eq!(submaximal_2.range.end(), &0x1_ffff);
assert_eq!(submaximal_2.value, start_val);

pub fn iter_ranges(&self) -> CodePointMapRangeIterator<'_, T>

Yields an Iterator returning ranges of consecutive code points that share the same value in the CodePointTrie, as given by CodePointTrie::get_range().

Examples

use core::ops::RangeInclusive;
use icu::collections::codepointtrie::planes;
use icu::collections::codepointtrie::CodePointMapRange;

let planes_trie = planes::get_planes_trie();

let mut ranges = planes_trie.iter_ranges();

for plane in 0..=16 {
    let exp_start = plane * 0x1_0000;
    let exp_end = exp_start + 0xffff;
    assert_eq!(
        ranges.next(),
        Some(CodePointMapRange {
            range: RangeInclusive::new(exp_start, exp_end),
            value: plane as u8
        })
    );
}

// Hitting the end of the iterator returns `None`, as will subsequent
// calls to .next().
assert_eq!(ranges.next(), None);
assert_eq!(ranges.next(), None);

pub fn get_ranges_for_value( &self, value: T, ) -> impl Iterator<Item = RangeInclusive<u32>> + '_

Yields an Iterator returning the ranges of the code points whose values match value in the CodePointTrie.

Examples

use icu::collections::codepointtrie::planes;

let trie = planes::get_planes_trie();

let plane_val = 2;
let mut sip_range_iter = trie.get_ranges_for_value(plane_val as u8);

let start = plane_val * 0x1_0000;
let end = start + 0xffff;

let sip_range = sip_range_iter.next()
    .expect("Plane 2 (SIP) should exist in planes data");
assert_eq!(start..=end, sip_range);

assert!(sip_range_iter.next().is_none());

pub fn iter_ranges_mapped<'a, U: Eq + 'a>( &'a self, map: impl FnMut(T) -> U + Copy + 'a, ) -> impl Iterator<Item = CodePointMapRange<U>> + 'a

Yields an Iterator returning the ranges of the code points after passing the value through a mapping function.

This is preferable to calling .get_ranges().map() since it will coalesce adjacent ranges into one.

Examples

use icu::collections::codepointtrie::planes;

let trie = planes::get_planes_trie();

let plane_val = 2;
let mut sip_range_iter = trie.iter_ranges_mapped(|value| value != plane_val as u8).filter(|range| range.value);

let end = plane_val * 0x1_0000 - 1;

let sip_range = sip_range_iter.next()
    .expect("Complemented planes data should have at least one entry");
assert_eq!(0..=end, sip_range.range);

pub fn get_set_for_value(&self, value: T) -> CodePointInversionList<'static>

Returns a CodePointInversionList for the code points that have the given TrieValue in the trie.

Examples

use icu::collections::codepointtrie::planes;

let trie = planes::get_planes_trie();

let plane_val = 2;
let sip = trie.get_set_for_value(plane_val as u8);

let start = plane_val * 0x1_0000;
let end = start + 0xffff;

assert!(!sip.contains32(start - 1));
assert!(sip.contains32(start));
assert!(sip.contains32(end));
assert!(!sip.contains32(end + 1));

pub fn error_value(&self) -> T

Returns the value used as an error value for this trie

impl<'trie, T: TrieValue + Into<u32>> CodePointTrie<'trie, T>

pub fn get32_u32(&self, code_point: u32) -> u32

Returns the value that is associated with code_point for this CodePointTrie as a u32.

Examples

use icu::collections::codepointtrie::planes;
let trie = planes::get_planes_trie();

let cp = '𑖎' as u32;
assert_eq!(cp, 0x1158E);

let plane_num: u8 = trie.get32(cp);
assert_eq!(trie.get32_u32(cp), plane_num as u32);

Trait Implementations

impl<'trie, T: TrieValue> Clone for CodePointTrie<'trie, T>

where <T as AsULE>::ULE: Clone,

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'trie, T: Debug + TrieValue> Debug for CodePointTrie<'trie, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'trie, T: PartialEq + TrieValue> PartialEq for CodePointTrie<'trie, T>

fn eq(&self, other: &CodePointTrie<'trie, T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T> Yokeable<'a> for CodePointTrie<'static, T>

where T: 'static + TrieValue,

type Output = CodePointTrie<'a, T>

This type MUST be Self with the 'static replaced with 'a, i.e. Self<'a>

fn transform(&'a self) -> &'a Self::Output

This method must cast self between &'a Self<'static> and &'a Self<'a>.

fn transform_owned(self) -> Self::Output

This method must cast self between Self<'static> and Self<'a>.

unsafe fn make(this: Self::Output) -> Self

This method can be used to cast away Self<'a>’s lifetime.

fn transform_mut<F>(&'a mut self, f: F)

where F: 'static + for<'b> FnOnce(&'b mut Self::Output),

This method must cast self between &'a mut Self<'static> and &'a mut Self<'a>, and pass it to f.

impl<'zf, 'zf_inner, T: TrieValue> ZeroFrom<'zf, CodePointTrie<'zf_inner, T>> for CodePointTrie<'zf, T>

where ZeroVec<'zf, T>: ZeroFrom<'zf, ZeroVec<'zf_inner, T>>,

fn zero_from(this: &'zf CodePointTrie<'zf_inner, T>) -> Self

Clone the other C into a struct that may retain references into C.

impl<'trie, T: Eq + TrieValue> Eq for CodePointTrie<'trie, T>

impl<'trie, T: TrieValue> StructuralPartialEq for CodePointTrie<'trie, T>