pub trait ValueRef: Borrow<Self::Target> + Clone {
type Target: Eq + Clone;
// Required method
fn into_value(self) -> Self::Target;
}Expand description
A trait for cloneable references to Eq + Clone values, used by the SortedDisjointMap trait.
ValueRef enables SortedDisjointMap to map sorted, disjoint ranges of integers
to values of type V: Eq + Clone. It supports both plain references (&V) and shared ownership types
(Rc<V> and Arc<V>), avoiding unnecessary cloning of values while enabling ownership when needed.
All types implementing ValueRef must also implement Clone. For standard reference types like
&V, Rc<V>, and Arc<V>, this is efficient—cloning typically just copies a pointer.
§Motivation
Iterating over (range, value) pairs—such as with RangeMapBlaze::ranges—benefits from
using references, which are cheap to clone. But other APIs, like RangeMapBlaze::into_ranges,
require owned values. ValueRef bridges this gap by abstracting over value references 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§
Required Methods§
Sourcefn into_value(self) -> Self::Target
fn into_value(self) -> Self::Target
Materializes a Self::Target (V) value from this reference-like container.
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:
&V→ callsClone::cloneonV. IfVis a reference (e.g.,&'static str), this simply copies the reference without allocation.Rc<V>/Arc<V>→ tries to unwrap if uniquely owned; otherwise clonesV.
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::ValueRef;
// 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", so this trait is not object safe.