rt_vec/lib.rs
1//! Runtime managed mutable borrowing from a vec.
2//!
3//! This library provides a vec that allows mutable borrows to different
4//! elements at the same time. For a map implementation of this, see [`rt_map`].
5//!
6//!
7//! ## Usage
8//!
9//! Add the following to `Cargo.toml`
10//!
11//! ```toml
12//! rt_vec = "0.1.1" # or
13//! rt_vec = { version = "0.1.1", features = ["unsafe_debug"] }
14//! ```
15//!
16//! In code:
17//!
18//! ```rust
19//! use rt_vec::RtVec;
20//!
21//! struct A(u32);
22//!
23//! let mut rt_vec = RtVec::new();
24//!
25//! rt_vec.push(A(1));
26//! rt_vec.push(A(2));
27//!
28//! // We can validly have two mutable borrows from the `RtVec` map!
29//! let mut a = rt_vec.borrow_mut(0);
30//! let mut b = rt_vec.borrow_mut(1);
31//! a.0 = 2;
32//! b.0 = 3;
33//!
34//! // We need to explicitly drop the A and B borrows, because they are runtime
35//! // managed borrows, and rustc doesn't know to drop them before the immutable
36//! // borrows after this.
37//! drop(a);
38//! drop(b);
39//!
40//! // Multiple immutable borrows to the same value are valid.
41//! let a_0 = rt_vec.borrow(0);
42//! let _a_1 = rt_vec.borrow(0);
43//! let b = rt_vec.borrow(1);
44//!
45//! println!("A: {}", a_0.0);
46//! println!("B: {}", b.0);
47//!
48//! // Trying to mutably borrow a value that is already borrowed (immutably
49//! // or mutably) returns `Err`.
50//! let a_try_borrow_mut = rt_vec.try_borrow_mut(0);
51//! let exists = if a_try_borrow_mut.is_ok() {
52//! "Ok(..)"
53//! } else {
54//! "Err"
55//! };
56//! println!("a_try_borrow_mut: {}", exists); // prints "Err"
57//! ```
58//!
59//!
60//! ### Features
61//!
62//! #### `"unsafe_debug"`
63//!
64//! Enables the [`"unsafe_debug"`] feature of [`rt_ref`].
65//!
66//!
67//! [`rt_map`]: https://crates.io/crates/rt_map
68//! [`"unsafe_debug"`]: https://github.com/azriel91/rt_ref#unsafe_debug
69
70// Re-exports
71pub use rt_ref::{BorrowFail, Cell, CellRef, CellRefMut, Ref, RefMut};
72
73pub use crate::rt_vec::RtVec;
74
75mod rt_vec;