Struct Set 

pub struct Set<T: Indexable> { /* private fields */ }

An owned set optimized for read-heavy workloads, backed by a PGM-index.

This is a BTreeSet-like container that owns its data and provides efficient lookups using a learned index. Mutations are supported but trigger O(n) index rebuilds; for frequent updates use crate::Dynamic.

Works with any type that implements Indexable:

• Numeric types (u64, i32, etc.) are indexed directly
• String/bytes types use prefix extraction

Example

use pgm_extra::Set;

// Numeric set
let nums: Vec<u64> = (0..10000).collect();
let set = Set::from_sorted_unique(nums, 64, 4).unwrap();
assert!(set.contains(&5000));

// String set
let words = vec!["apple", "banana", "cherry"];
let set = Set::from_sorted_unique(words, 64, 4).unwrap();
assert!(set.contains(&"banana"));

Implementations

impl<T: Indexable + Ord> Set<T>

where T::Key: Ord,

pub fn from_sorted_unique( data: Vec<T>, epsilon: usize, epsilon_recursive: usize, ) -> Result<Self, Error>

Create a set from pre-sorted, unique values.

Panics

Debug builds will panic if values are not sorted or contain duplicates.

pub fn build<I>( iter: I, epsilon: usize, epsilon_recursive: usize, ) -> Result<Self, Error>

where I: IntoIterator<Item = T>,

Create a set from an unsorted iterator.

Values are sorted and deduplicated (like BTreeSet::from_iter).

pub fn empty(epsilon: usize, epsilon_recursive: usize) -> Self

Create an empty set with the given epsilon values.

pub fn new(data: Vec<T>) -> Result<Self, Error>

Create a set with default epsilon values (64, 4).

pub fn contains(&self, value: &T) -> bool

Check if the set contains the value.

pub fn get(&self, value: &T) -> Option<&T>

Get a reference to the value if it exists.

pub fn lower_bound(&self, value: &T) -> usize

Find the index of the first value >= the given value.

pub fn upper_bound(&self, value: &T) -> usize

Find the index of the first value > the given value.

pub fn range<R>(&self, range: R) -> impl DoubleEndedIterator<Item = &T>

where R: RangeBounds<T>,

Returns an iterator over values in the given range.

pub fn first(&self) -> Option<&T>

Get the first (smallest) value.

pub fn last(&self) -> Option<&T>

Get the last (largest) value.

pub fn iter(&self) -> impl ExactSizeIterator<Item = &T> + DoubleEndedIterator

Iterate over all values in sorted order.

pub fn len(&self) -> usize

Get the number of values.

pub fn is_empty(&self) -> bool

Check if the set is empty.

pub fn segments_count(&self) -> usize

Get the number of segments in the underlying index.

pub fn height(&self) -> usize

Get the height of the underlying index.

pub fn epsilon(&self) -> usize

Get the epsilon value.

pub fn epsilon_recursive(&self) -> usize

Get the epsilon_recursive value.

pub fn size_in_bytes(&self) -> usize

Approximate memory usage in bytes.

pub fn as_slice(&self) -> &[T]

Get a reference to the underlying data slice.

pub fn into_vec(self) -> Vec<T>

Consume the set and return the underlying data.

pub fn index(&self) -> Option<&Static<T>>

Get a reference to the underlying index.

pub fn insert(&mut self, value: T) -> bool

Insert a value into the set.

Returns true if the value was newly inserted, false if it already existed.

Note: This rebuilds the entire index, making it O(n) per insertion. For bulk insertions, prefer collecting into a new set or using extend. For frequent mutations, consider using index::owned::Dynamic directly.

pub fn is_disjoint(&self, other: &Set<T>) -> bool

Returns true if self has no elements in common with other.

pub fn is_subset(&self, other: &Set<T>) -> bool

Returns true if self is a subset of other.

pub fn is_superset(&self, other: &Set<T>) -> bool

Returns true if self is a superset of other.

pub fn difference<'a>( &'a self, other: &'a Set<T>, ) -> impl Iterator<Item = &'a T>

Returns an iterator over values in self but not in other.

pub fn symmetric_difference<'a>( &'a self, other: &'a Set<T>, ) -> impl Iterator<Item = &'a T>

Returns an iterator over values in self or other but not both.

pub fn intersection<'a>( &'a self, other: &'a Set<T>, ) -> impl Iterator<Item = &'a T>

Returns an iterator over values in both self and other.

pub fn union<'a>(&'a self, other: &'a Set<T>) -> impl Iterator<Item = &'a T>

Returns an iterator over values in either self or other.

Trait Implementations

impl<T: Indexable + Clone> Clone for Set<T>

where T::Key: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Indexable + Debug> Debug for Set<T>

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

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for Set<T>

where T: Serialize + DeserializeOwned + Indexable, T::Key: Serialize + DeserializeOwned,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Indexable + Ord> Extend<T> for Set<T>

where T::Key: Ord,

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends the set with elements from an iterator.

Note: This rebuilds the entire index, making it O(n) per call. For bulk insertions, prefer collecting into a new set. For frequent mutations, consider using index::owned::Dynamic directly.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T: Indexable + Ord> FromIterator<T> for Set<T>

where T::Key: Ord,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a Set from an iterator.

Returns an empty set if the iterator is empty.

impl<T: Indexable + Hash> Hash for Set<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, T: Indexable> IntoIterator for &'a Set<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Indexable + Ord> IntoIterator for Set<T>

where T::Key: Ord,

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Indexable + Ord> Ord for Set<T>

where T::Key: Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: Indexable + Ord + PartialEq> PartialEq for Set<T>

fn eq(&self, other: &Self) -> 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<T: Indexable + Ord + PartialOrd> PartialOrd for Set<T>

where T::Key: Ord,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Serialize for Set<T>

where T: Serialize + DeserializeOwned + Indexable, T::Key: Serialize + DeserializeOwned,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Indexable + Ord + Eq> Eq for Set<T>