Expand description
rc-slice2
The rc-slice2 library provides RcSlice and ArcSlice types representing
slices of array-like data structures contained within Rc and Arc.
Supports raw arrays, boxed slices, Vec, and SmallVec (with feature
smallvec). Includes limited support for resizing the original array, to
conserve memory.
The library is fully no_std, and has zero unsafe blocks. Every function
is now fully tested with examples and thorough documentation.
What happened to rc_slice?
rc-slice2 is the successor to the rc_slice crate. Ownership was not
transferred due to supply chain trust concerns. This crate’s 0.3.1
version is fully backwards compatible with rc_slice 0.3.0. Version
0.4.0 includes a minor breaking change, because the method of specifying
generic parameters was changed. However, the behavior of the API is still
backwards compatible.
Usage
rc-slice2 = "0.4"
extern crate alloc;
use rc_slice2::RcSlice;
use alloc::rc::Rc;
use RcSlice as Rcs;
let buffer: Rc<[u8]> = Rc::new([2, 4, 6, 8, 10]);
// Supports all kinds of slicing during construction
assert_eq!(*Rcs::new(&buffer, 1..4), [4, 6, 8]);
assert_eq!(*Rcs::new(&buffer, ..), [2, 4, 6, 8, 10]);
assert_eq!(*Rcs::new(&buffer, 0..=2), [2, 4, 6]);
assert_eq!(*Rcs::new(&buffer, 10..), []);
// Behaves like any other slice.
let mut slice = Rcs::new(&buffer, 1..);
assert_eq!(*slice, [4, 6, 8, 10]);
assert_eq!(slice[2..], [8, 10]);
assert_eq!(slice[1], 6);
// The slice can shrink, and returns cut-off elements.
assert_eq!(Rcs::advance(&mut slice, 2), Some([4, 6].as_slice()));
assert_eq!(*slice, [8, 10]);
assert_eq!(Rcs::retract(&mut slice, 1), Some([10].as_slice()));
assert_eq!(*slice, [8]);
// If the original buffer can change size, and there is only one
// strong reference, then the buffer can be shrunk to the slice.
let buffer = Rc::new(vec![12, 14, 16, 18, 20]);
let mut slice = Rcs::new(&buffer, 2..4);
assert_eq!(*slice, [16, 18]);
// Fails because `buffer` is still alive.
assert_eq!(Rcs::shrink(&mut slice), false);
let weak_buffer = Rc::downgrade(&buffer);
core::mem::drop(buffer);
// Success; only one strong reference. Original buffer has been shrunk.
assert_eq!(Rcs::shrink(&mut slice), true);
let buffer = Rcs::inner(&slice).clone();
assert_eq!(*buffer, [16, 18]);
// But weak references were not preserved.
assert_eq!(weak_buffer.upgrade(), None);
License
rc-slice2 is released under the terms of the Apache License, version 2.0 (see LICENSE-APACHE) or the MIT license (see LICENSE-MIT), at your option.
Structs
- A read-only view into part of an underlying atomically reference-counted slice.
- A read-only view into part of an underlying reference-counted slice.
Traits
- Trait implemented by any RcSlice-able container. Currently implemented for arrays, boxed arrays, and vectors.