1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5//! This module provides necessary functionality for highly efficient querying of sets of Unicode characters.
6//!
7//! It is an implementation of the code point portion of the existing
8//! [ICU4C UnicodeSet API](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1UnicodeSet.html).
9//!
10//! # Architecture
11//! ICU4X [`CodePointInversionList`] is split up into independent levels, with [`CodePointInversionList`] representing the membership/query API,
12//! and [`CodePointInversionListBuilder`] representing the builder API.
13//!
14//! # Examples:
15//!
16//! ## Creating a `CodePointInversionList`
17//!
18//! `CodePointSets` are created from either serialized [`CodePointSets`](CodePointInversionList),
19//! represented by [inversion lists](http://userguide.icu-project.org/strings/properties),
20//! the [`CodePointInversionListBuilder`], or from the Properties API.
21//!
22//! ```
23//! use icu::collections::codepointinvlist::{
24//! CodePointInversionList, CodePointInversionListBuilder,
25//! };
26//!
27//! let mut builder = CodePointInversionListBuilder::new();
28//! builder.add_range(&('A'..='Z'));
29//! let set: CodePointInversionList = builder.build();
30//!
31//! assert!(set.contains('A'));
32//! ```
33//!
34//! ## Querying a `CodePointInversionList`
35//!
36//! Currently, you can check if a character/range of characters exists in the [`CodePointInversionList`], or iterate through the characters.
37//!
38//! ```
39//! use icu::collections::codepointinvlist::{
40//! CodePointInversionList, CodePointInversionListBuilder,
41//! };
42//!
43//! let mut builder = CodePointInversionListBuilder::new();
44//! builder.add_range(&('A'..='Z'));
45//! let set: CodePointInversionList = builder.build();
46//!
47//! assert!(set.contains('A'));
48//! assert!(set.contains_range(&('A'..='C')));
49//! assert_eq!(set.iter_chars().next(), Some('A'));
50//! ```
51//!
52//! [`ICU4X`]: ../icu/index.html
53
54#![warn(missing_docs)]
55
56extern crate alloc;
57
58#[macro_use]
59mod builder;
60mod conversions;
61mod cpinvlist;
62mod utils;
63
64use alloc::vec::Vec;
65
66pub use builder::CodePointInversionListBuilder;
67pub use cpinvlist::CodePointInversionList;
68pub use cpinvlist::CodePointInversionListULE;
69use displaydoc::Display;
70
71/// Custom Errors for [`CodePointInversionList`].
72///
73/// Re-exported as [`Error`].
74#[derive(Display, Debug)]
75pub enum CodePointInversionListError {
76 /// A CodePointInversionList was constructed with an invalid inversion list
77 #[displaydoc("Invalid set: {0:?}")]
78 InvalidSet(Vec<u32>),
79 /// A CodePointInversionList was constructed containing an invalid range
80 #[displaydoc("Invalid range: {0}..{1}")]
81 InvalidRange(u32, u32),
82}
83
84#[cfg(feature = "std")]
85impl std::error::Error for CodePointInversionListError {}
86
87#[doc(no_inline)]
88pub use CodePointInversionListError as Error;
89