Enum CowSplinter 

pub enum CowSplinter<B> {
    Ref(SplinterRef<B>),
    Owned(Splinter),
}

A clone-on-write splinter that can hold either a reference or an owned value.

CowSplinter is an enum that can contain either a SplinterRef<B> (for zero-copy read-only access) or an owned Splinter (for mutable operations). It automatically converts from read-only to owned when mutation is needed, providing an efficient way to work with splinter data that might come from different sources.

This is particularly useful when you want to:

• Start with serialized/borrowed data for read-only operations
• Potentially modify the data later
• Avoid unnecessary copying until mutation is actually needed
• Or work with a collection of Splinters which may or may not be owned

Examples

Starting with a reference and converting to owned when needed:

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

// Create a CowSplinter from a reference
let original = Splinter::from_iter([100, 200]);
let splinter_ref = original.encode_to_splinter_ref();
let mut cow = CowSplinter::from_ref(splinter_ref);

// Read operations work on the reference
assert_eq!(cow.cardinality(), 2);

// First write operation converts to owned
cow.insert(300); // This triggers clone-on-write
assert_eq!(cow.cardinality(), 3);

Creating from different sources:

use splinter_rs::{Splinter, CowSplinter, PartitionWrite, PartitionRead, Encodable};
use bytes::Bytes;

// From owned splinter
let owned = Splinter::EMPTY;
let cow1: CowSplinter<Bytes> = CowSplinter::from_owned(owned);

// From iterator
let cow2 = CowSplinter::<Bytes>::from_iter([1u32, 2, 3]);

// From bytes
let bytes = cow2.encode_to_bytes();
let cow3 = CowSplinter::from_bytes(bytes).unwrap();

Variants

Ref(SplinterRef<B>)

Contains a zero-copy reference to serialized data

Owned(Splinter)

Contains an owned, mutable splinter

Implementations

impl<B> CowSplinter<B>

pub fn from_owned(splinter: Splinter) -> Self

Creates a CowSplinter from an owned Splinter.

Examples

use splinter_rs::{Splinter, CowSplinter, PartitionRead, Encodable};

let splinter = Splinter::from_iter([42]);
let cow: CowSplinter<Vec<u8>> = CowSplinter::from_owned(splinter);
assert!(cow.contains(42));

pub fn from_ref(splinter: SplinterRef<B>) -> Self

Creates a CowSplinter from a SplinterRef.

Examples

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

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

let cow = CowSplinter::from_ref(splinter_ref);
assert!(cow.contains(42));

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

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

Creates a CowSplinter from raw bytes, validating the format.

This is equivalent to creating a SplinterRef from the bytes and wrapping it in a CowSplinter::Ref. All the same validation rules apply.

Errors

Returns the same errors as SplinterRef::from_bytes.

Examples

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

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

let cow = CowSplinter::from_bytes(bytes).unwrap();
assert!(cow.contains(42));

pub fn into_owned(self) -> Splinter

Converts this CowSplinter into an owned Splinter.

If this is already an owned splinter, it returns it directly. If this is a reference, it deserializes the data into a new owned splinter.

Examples

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

let mut original = Splinter::EMPTY;
original.insert(100);
let splinter_ref = original.encode_to_splinter_ref();
let cow = CowSplinter::from_ref(splinter_ref);

let owned = cow.into_owned();
assert_eq!(owned.cardinality(), 1);
assert!(owned.contains(100));

pub fn to_mut(&mut self) -> &mut Splinter

Returns a mutable reference to the underlying Splinter.

This method implements the “clone-on-write” behavior: if the current value is a Ref, it will be converted to Owned by deserializing the data. Subsequent calls will return the same mutable reference without additional conversions.

Examples

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

let mut original = Splinter::EMPTY;
original.insert(100);
let splinter_ref = original.encode_to_splinter_ref();
let mut cow = CowSplinter::from_ref(splinter_ref);

// This triggers the clone-on-write conversion
let mutable_ref = cow.to_mut();
mutable_ref.insert(200);

assert_eq!(cow.cardinality(), 2);

impl CowSplinter<Bytes>

pub fn encode_to_bytes(&self) -> Bytes

Returns the serialized bytes representation of this splinter.

For the Ref variant, this clones the underlying Bytes (which is efficient due to reference counting). For the Owned variant, this encodes the splinter to bytes.

Examples

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

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

let bytes = cow.encode_to_bytes();
assert!(!bytes.is_empty());

Trait Implementations

impl<B: Clone> Clone for CowSplinter<B>

fn clone(&self) -> CowSplinter<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<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]>> Debug for CowSplinter<B>

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

Formats the value using the given formatter.

impl<B> Default for CowSplinter<B>

fn default() -> Self

Returns the “default value” for a type.

impl<B: Deref<Target = [u8]>> Encodable for CowSplinter<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<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 From<CowSplinter<Bytes>> for SplinterRef<Bytes>

fn from(cow: CowSplinter<Bytes>) -> 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<B> From<SplinterRef<B>> for CowSplinter<B>

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

Converts to this type from the input type.

impl<B, K: Into<u32>> FromIterator<K> for CowSplinter<B>

where B: Deref<Target = [u8]>,

fn from_iter<I: IntoIterator<Item = K>>(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]>> 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]>, B2: Deref<Target = [u8]>> PartialEq<CowSplinter<B2>> for CowSplinter<B>

fn eq(&self, other: &CowSplinter<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 CowSplinter<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]>> PartitionWrite<High> for CowSplinter<B>

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

Inserts the value into the partition unless it already exists. Returns true if the insertion occurred, false otherwise.

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

Removes the value from the partition if it exists. Returns true if the removal occurred, false otherwise.

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