Trait ValueCarrier 

pub trait ValueCarrier: Clone {
    type Value: Eq + Clone;

    // Required methods
    fn value_eq(&self, other: &Self) -> bool;
    fn into_value(self) -> Self::Value;
}

A cheap-to-clone representation that carries a logical Eq + Clone value for use by SortedDisjointMap.

ValueCarrier enables SortedDisjointMap to map sorted, disjoint ranges of integers to values of type V: Eq + Clone. It supports plain references (&V), shared ownership types (Rc<V> and Arc<V>), compound carriers such as Option<&V>, and the by-value bool carrier, avoiding unnecessary cloning of values while enabling ownership when needed.

All types implementing ValueCarrier must also implement Clone. For standard carriers like &V, Rc<V>, Arc<V>, their Option forms, and bool, this is efficient—cloning typically just copies a pointer and a discriminant or a small value.

Motivation

Iterating over (range, value) pairs—such as with RangeMapBlaze::range_values—benefits from using cheap-to-clone representations. Other APIs, like RangeMapBlaze::into_range_values, require owned values. ValueCarrier bridges this gap by abstracting over carriers that can later be materialized into values you can store or return independently of the original container.

This also enables shared ownership via Rc and Arc, reducing allocation and allowing values to be freed when the reference count drops to zero.

Examples

The following demonstrates the SortedDisjointMap::intersection operation working with iterators of both (RangeInclusive<Integer>, &Eq + Clone) and (RangeInclusive<Integer>, Rc<Eq + Clone>). (However, types cannot be mixed in the same operation due to Rust’s strong type system.)

use range_set_blaze::prelude::*;
use std::rc::Rc;

let a = RangeMapBlaze::from_iter([(3..=10, "a".to_string())]);
let b = RangeMapBlaze::from_iter([(2..=3, "b".to_string()), (5..=100, "b".to_string())]);

let mut c = a.range_values() & b.range_values();
assert_eq!(c.next(), Some((3..=3, &"b".to_string())));
assert_eq!(c.next(), Some((5..=10, &"b".to_string())));
assert_eq!(c.next(), None);

let mut c = a.into_range_values() & b.into_range_values();
assert_eq!(c.next(), Some((3..=3, Rc::new("b".to_string()))));
assert_eq!(c.next(), Some((5..=10, Rc::new("b".to_string()))));
assert_eq!(c.next(), None);

Required Associated Types

type Value: Eq + Clone

The logical Eq + Clone value represented by this carrier.

Required Methods

fn value_eq(&self, other: &Self) -> bool

Compares the logical values represented by two value carriers.

This deliberately avoids requiring Borrow<Self::Value>: compound representations such as Option<&V> cannot borrow an Option<V> without first materializing one, but can still compare their logical values cheaply. Implementations must define an equivalence relation and agree with comparing the results of ValueCarrier::into_value.

fn into_value(self) -> Self::Value

Materializes a Self::Value (V) value from this carrier.

The returned V may or may not be a uniquely owned allocation. If V itself is a reference type (e.g., &'static str), the result is still a reference; in that case this operation is just a cheap pointer copy. In other words, “owned” here means “a standalone V value you can keep,” not necessarily a unique heap allocation.

Behavior:

• bool → returns itself.
• &V → calls Clone::clone on V. If V is a reference (e.g., &'static str), this simply copies the reference without allocation.
• Rc<V> / Arc<V> → tries to unwrap if uniquely owned; otherwise clones V.

This is typically used when converting a stream of (range, value) pairs into values that can be stored or returned independently of the original container.

Examples

use std::rc::Rc;
use range_set_blaze::ValueCarrier;

// Owning target: cloning duplicates the data
let s = String::from("hi");
let owned_s: String = (&s).into_value(); // clones the String

// Reference target: no allocation; still a reference
let static_s: &'static str = "hi";
let r: &&'static str = &static_s;
let still_ref: &'static str = r.into_value(); // copies the reference

// Rc: move out if unique, else clone
let rc = Rc::new(String::from("hello"));
let moved_or_cloned: String = rc.into_value();

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl ValueCarrier for bool

type Value = bool

fn value_eq(&self, other: &Self) -> bool

fn into_value(self) -> Self::Value

impl<V> ValueCarrier for &V

where V: Eq + Clone,

type Value = V

fn value_eq(&self, other: &Self) -> bool

fn into_value(self) -> Self::Value

impl<V> ValueCarrier for Arc<V>

where V: Eq + Clone,

Available on crate feature std only.

type Value = V

fn value_eq(&self, other: &Self) -> bool

fn into_value(self) -> Self::Value

impl<V> ValueCarrier for Rc<V>

where V: Eq + Clone,

type Value = V

fn value_eq(&self, other: &Self) -> bool

fn into_value(self) -> Self::Value

impl<VC> ValueCarrier for Option<VC>

where VC: ValueCarrier,

type Value = Option<<VC as ValueCarrier>::Value>

fn value_eq(&self, other: &Self) -> bool

fn into_value(self) -> Self::Value

Implementors