Struct SplinterRef 

pub struct SplinterRef<B> { /* private fields */ }

A zero-copy reference to serialized splinter data.

SplinterRef allows efficient querying of compressed bitmap data without deserializing the underlying structure. It wraps any type that can be dereferenced to [u8] and provides all the same read operations as Splinter, but with minimal memory overhead and no allocation during queries.

This is the preferred type for read-only operations on serialized splinter data, especially when the data comes from files, network, or other external sources.

Type Parameter

• B: Any type that implements Deref<Target = [u8]> such as &[u8], Vec<u8>, Bytes, Arc<[u8]>, etc.

Examples

Creating from serialized bytes:

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

// Create and populate a splinter
let mut splinter = Splinter::EMPTY;
splinter.insert(100);
splinter.insert(200);

// Serialize it to bytes
let bytes = splinter.encode_to_bytes();

// Create a zero-copy reference
let splinter_ref = SplinterRef::from_bytes(bytes).unwrap();
assert_eq!(splinter_ref.cardinality(), 2);
assert!(splinter_ref.contains(100));

Working with different buffer types:

use splinter_rs::{Splinter, SplinterRef, PartitionWrite, PartitionRead, Encodable};
use std::sync::Arc;

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

let bytes = splinter.encode_to_bytes();
let shared_bytes: Arc<[u8]> = bytes.to_vec().into();

let splinter_ref = SplinterRef::from_bytes(shared_bytes).unwrap();
assert!(splinter_ref.contains(42));

Implementations

impl<B> SplinterRef<B>

pub fn inner(&self) -> &B

Returns a reference to the underlying data buffer.

This provides access to the raw bytes that store the serialized splinter data.

Examples

use splinter_rs::{Splinter, SplinterRef, PartitionWrite, Encodable};

let mut splinter = Splinter::EMPTY;
splinter.insert(42);
let bytes = splinter.encode_to_bytes();
let splinter_ref = SplinterRef::from_bytes(bytes).unwrap();

let inner_bytes = splinter_ref.inner();
assert!(!inner_bytes.is_empty());

pub fn into_inner(self) -> B

Consumes the SplinterRef and returns the underlying data buffer.

This is useful when you need to take ownership of the underlying data after you’re done querying the splinter.

Examples

use splinter_rs::{Splinter, SplinterRef, PartitionWrite, Encodable};

let mut splinter = Splinter::EMPTY;
splinter.insert(42);
let bytes = splinter.encode_to_bytes();
let splinter_ref = SplinterRef::from_bytes(bytes.clone()).unwrap();

let recovered_bytes = splinter_ref.into_inner();
assert_eq!(recovered_bytes, bytes);

impl SplinterRef<Bytes>

pub fn encode_to_bytes(&self) -> Bytes

Returns a clone of the underlying bytes.

This is efficient for Bytes since it uses reference counting internally and doesn’t actually copy the data.

Examples

use splinter_rs::{Splinter, PartitionWrite};

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

let bytes_copy = splinter_ref.encode_to_bytes();
assert!(!bytes_copy.is_empty());

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

pub fn decode_to_splinter(&self) -> Splinter

Converts this reference back to an owned Splinter.

This method deserializes the underlying data and creates a new owned Splinter that supports mutation. This involves iterating through all values and rebuilding the data structure, so it has a cost proportional to the number of elements.

Examples

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

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

let splinter_ref = original.encode_to_splinter_ref();
let decoded = splinter_ref.decode_to_splinter();

assert_eq!(decoded.cardinality(), 2);
assert!(decoded.contains(100));
assert!(decoded.contains(200));

pub fn from_bytes(data: B) -> Result<Self, DecodeErr>

Creates a SplinterRef from raw bytes, validating the format.

This method parses and validates the serialized splinter format, checking:

• Sufficient data length
• Valid magic bytes
• Correct checksum

IMPORTANT: This method does not recursively verify the entire splinter, opting instead to rely on the checksum to detect any corruption. Do not use Splinter with untrusted data as it’s trivial to construct a Splinter which will cause your program to panic at runtime.

Returns an error if the data is corrupted or in an invalid format.

Errors

• DecodeErr::Length: Not enough bytes in the buffer
• DecodeErr::Magic: Invalid magic bytes
• DecodeErr::Checksum: Data corruption detected
• DecodeErr::Validity: Invalid internal structure
• DecodeErr::SplinterV1: Data is from incompatible v1 format

Examples

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

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

let splinter_ref = SplinterRef::from_bytes(bytes).unwrap();
assert!(splinter_ref.contains(42));

Error handling:

use splinter_rs::{SplinterRef, codec::DecodeErr};

let invalid_bytes = vec![0u8; 5]; // Too short
let result = SplinterRef::from_bytes(invalid_bytes);
assert!(matches!(result.unwrap_err().ctx(), DecodeErr::Length));

Trait Implementations

impl<B: Clone> Clone for SplinterRef<B>

fn clone(&self) -> SplinterRef<B>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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<B: Deref<Target = [u8]>> Debug for SplinterRef<B>

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

Formats the value using the given formatter.

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

fn encoded_size(&self) -> usize

Returns the number of bytes required to encode this value.

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

Encodes this value into the provided encoder.

fn encode_to_bytes(&self) -> Bytes

Convenience method that encodes this value to a Bytes buffer.

impl From<CowSplinter<Bytes>> for SplinterRef<Bytes>

fn from(cow: CowSplinter<Bytes>) -> Self

Converts to this type from the input type.

impl<B> From<SplinterRef<B>> for CowSplinter<B>

fn from(splinter_ref: SplinterRef<B>) -> Self

Converts to this type from the input type.

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

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

Merges rhs into self

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<B: Deref<Target = [u8]>, B2: Deref<Target = [u8]>> PartialEq<SplinterRef<B2>> for SplinterRef<B>

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

fn cardinality(&self) -> usize

the total number of values accessible via this partition.

fn is_empty(&self) -> bool

returns true if this partition is empty

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

returns true if this partition contains the given value

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

returns the number of values contained in this partition up to and including the value.

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

returns the value at position idx.

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

returns the last value in the partition

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

returns an iterator over all values in this partition

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<B: Deref<Target = [u8]>> Eq for SplinterRef<B>