Struct Splinter 

pub struct Splinter(/* private fields */);

A compressed bitmap optimized for small, sparse sets of 32-bit unsigned integers.

Splinter is the main owned data structure that can be built incrementally by inserting values and then optimized for size and query performance. It uses a 256-way tree structure by decomposing integers into big-endian component bytes, with nodes optimized into four different storage classes: tree, vec, bitmap, and run.

For zero-copy querying of serialized data, see SplinterRef. For a clone-on-write wrapper, see CowSplinter.

Examples

Basic usage:

use splinter_rs::{Splinter, PartitionWrite, PartitionRead, Optimizable};

let mut splinter = Splinter::EMPTY;

// Insert some values
splinter.insert(1024);
splinter.insert(2048);
splinter.insert(123);

// Check membership
assert!(splinter.contains(1024));
assert!(!splinter.contains(999));

// Get cardinality
assert_eq!(splinter.cardinality(), 3);

// Optimize for better compression, recommended before encoding to bytes.
splinter.optimize();

Building from iterator:

use splinter_rs::{Splinter, PartitionRead};

let values = vec![100, 200, 300, 400];
let splinter: Splinter = values.into_iter().collect();

assert_eq!(splinter.cardinality(), 4);
assert!(splinter.contains(200));

Implementations

impl Splinter

pub const EMPTY: Self

An empty Splinter, suitable for usage in a const context.

pub fn encode_to_splinter_ref(&self) -> SplinterRef<Bytes>

Encodes this splinter into a SplinterRef for zero-copy querying.

This method serializes the splinter data and returns a SplinterRef<Bytes> that can be used for efficient read-only operations without deserializing the underlying data structure.

Examples

use splinter_rs::{Splinter, PartitionWrite, PartitionRead};

let mut splinter = Splinter::EMPTY;
splinter.insert(42);
splinter.insert(1337);

let splinter_ref = splinter.encode_to_splinter_ref();
assert_eq!(splinter_ref.cardinality(), 2);
assert!(splinter_ref.contains(42));

Trait Implementations

impl Clone for Splinter

fn clone(&self) -> Splinter

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<B: Deref<Target = [u8]>> Cut<CowSplinter<B>> for Splinter

type Out = Splinter

fn cut(&mut self, rhs: &CowSplinter<B>) -> Self::Out

Returns the intersection between self and other while removing the intersection from self

impl<B: Deref<Target = [u8]>> Cut<SplinterRef<B>> for Splinter

type Out = Splinter

fn cut(&mut self, rhs: &SplinterRef<B>) -> Self::Out

Returns the intersection between self and other while removing the intersection from self

impl Cut for Splinter

type Out = Splinter

fn cut(&mut self, rhs: &Self) -> Self::Out

Returns the intersection between self and other while removing the intersection from self

impl Debug for Splinter

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

Formats the value using the given formatter.

impl Default for Splinter

fn default() -> Splinter

Returns the “default value” for a type.

impl Encodable for Splinter

fn encoded_size(&self) -> usize

Returns the number of bytes required to encode this value.

fn encode<B: BufMut>(&self, encoder: &mut Encoder<B>)

Encodes this value into the provided encoder.

fn encode_to_bytes(&self) -> Bytes

Convenience method that encodes this value to a Bytes buffer.

impl<B: Deref<Target = [u8]>> From<CowSplinter<B>> for Splinter

fn from(cow_splinter: CowSplinter<B>) -> Self

Converts to this type from the input type.

impl<B> From<Splinter> for CowSplinter<B>

fn from(splinter: Splinter) -> Self

Converts to this type from the input type.

impl FromIterator<u32> for Splinter

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

Creates a value from an iterator.

impl<B: Deref<Target = [u8]>> Merge<CowSplinter<B>> for Splinter

fn merge(&mut self, rhs: &CowSplinter<B>)

Merges rhs into self

impl<B: Deref<Target = [u8]>> Merge<SplinterRef<B>> for Splinter

fn merge(&mut self, rhs: &SplinterRef<B>)

Merges rhs into self

impl Merge for Splinter

fn merge(&mut self, rhs: &Self)

Merges rhs into self

impl Optimizable for Splinter

fn optimize(&mut self)

Optimize memory usage. Should be run after batch inserts or before serialization.

impl<B: Deref<Target = [u8]>> PartialEq<CowSplinter<B>> for Splinter

fn eq(&self, other: &CowSplinter<B>) -> 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<B: Deref<Target = [u8]>> PartialEq<Splinter> for SplinterRef<B>

fn eq(&self, other: &Splinter) -> 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<B: Deref<Target = [u8]>> PartialEq<SplinterRef<B>> for Splinter

fn eq(&self, other: &SplinterRef<B>) -> 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 PartialEq for Splinter

fn eq(&self, other: &Splinter) -> 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 PartitionRead<High> for Splinter

fn cardinality(&self) -> usize

Returns the total number of elements in this splinter.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
assert_eq!(splinter.cardinality(), 0);

splinter.insert(100);
splinter.insert(200);
splinter.insert(300);
assert_eq!(splinter.cardinality(), 3);

fn is_empty(&self) -> bool

Returns true if this splinter contains no elements.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
assert!(splinter.is_empty());

splinter.insert(42);
assert!(!splinter.is_empty());

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

Returns true if this splinter contains the specified value.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
splinter.insert(42);
splinter.insert(1337);

assert!(splinter.contains(42));
assert!(splinter.contains(1337));
assert!(!splinter.contains(999));

fn rank(&self, value: u32) -> usize

Returns the number of elements in this splinter that are less than or equal to the given value.

This is also known as the “rank” of the value in the sorted sequence of all elements.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
splinter.insert(10);
splinter.insert(20);
splinter.insert(30);

assert_eq!(splinter.rank(5), 0);   // No elements <= 5
assert_eq!(splinter.rank(10), 1);  // One element <= 10
assert_eq!(splinter.rank(25), 2);  // Two elements <= 25
assert_eq!(splinter.rank(30), 3);  // Three elements <= 30
assert_eq!(splinter.rank(50), 3);  // Three elements <= 50

fn select(&self, idx: usize) -> Option<u32>

Returns the element at the given index in the sorted sequence, or None if the index is out of bounds.

The index is 0-based, so select(0) returns the smallest element.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
splinter.insert(100);
splinter.insert(50);
splinter.insert(200);

assert_eq!(splinter.select(0), Some(50));   // Smallest element
assert_eq!(splinter.select(1), Some(100));  // Second smallest
assert_eq!(splinter.select(2), Some(200));  // Largest element
assert_eq!(splinter.select(3), None);       // Out of bounds

fn last(&self) -> Option<u32>

Returns the largest element in this splinter, or None if it’s empty.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
assert_eq!(splinter.last(), None);

splinter.insert(100);
splinter.insert(50);
splinter.insert(200);

assert_eq!(splinter.last(), Some(200));

fn iter(&self) -> impl Iterator<Item = u32>

Returns an iterator over all elements in ascending order.

Examples

use splinter_rs::{Splinter, PartitionRead, PartitionWrite};

let mut splinter = Splinter::EMPTY;
splinter.insert(300);
splinter.insert(100);
splinter.insert(200);

let values: Vec<u32> = splinter.iter().collect();
assert_eq!(values, vec![100, 200, 300]);

fn range<R>(&self, range: R) -> impl Iterator<Item = L::Value>

where R: RangeBounds<L::Value> + Clone,

returns an iterator over all values in this partition restricted by the provided range.

impl PartitionWrite<High> for Splinter

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

Inserts a value into this splinter.

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

Examples

use splinter_rs::{Splinter, PartitionWrite, PartitionRead};

let mut splinter = Splinter::EMPTY;

// First insertion returns true
assert!(splinter.insert(42));
assert_eq!(splinter.cardinality(), 1);

// Second insertion of same value returns false
assert!(!splinter.insert(42));
assert_eq!(splinter.cardinality(), 1);

// Different value returns true
assert!(splinter.insert(100));
assert_eq!(splinter.cardinality(), 2);

fn remove(&mut self, value: u32) -> bool

Removes a value from this splinter.

Returns true if the value was present and removed, or false if it was not present.

Examples

use splinter_rs::{Splinter, PartitionWrite, PartitionRead};

let mut splinter = Splinter::EMPTY;
splinter.insert(42);
splinter.insert(100);
assert_eq!(splinter.cardinality(), 2);

// Remove existing value
assert!(splinter.remove(42));
assert_eq!(splinter.cardinality(), 1);
assert!(!splinter.contains(42));
assert!(splinter.contains(100));

// Remove non-existent value
assert!(!splinter.remove(999));
assert_eq!(splinter.cardinality(), 1);

impl Eq for Splinter

impl StructuralPartialEq for Splinter