unsafe_cell_slice 0.1.0

A microlibrary for creating multiple mutable references to a slice
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

# unsafe_cell_slice

[![Latest Version](https://img.shields.io/crates/v/unsafe_cell_slice.svg)](https://crates.io/crates/unsafe_cell_slice)
[![unsafe_cell_slice documentation](https://docs.rs/unsafe_cell_slice/badge.svg)](https://docs.rs/unsafe_cell_slice)
![msrv](https://img.shields.io/crates/msrv/unsafe_cell_slice)
[![build](https://github.com/LDeakin/unsafe_cell_slice/actions/workflows/ci.yml/badge.svg)](https://github.com/LDeakin/unsafe_cell_slice/actions/workflows/ci.yml)

A Rust microlibrary for creating multiple mutable references to a `slice`.

### Motivation
The rust borrow checker forbids creating multiple mutable references of a `slice`.
For example, this fails to compile with ```cannot borrow `data` as mutable more than once at a time```:
```rust
let mut data = vec![0u8; 2];
let data_a: &mut [u8] = data.as_mut_slice();
let data_b: &mut [u8] = data.as_mut_slice();
data_a[0] = 0;
data_b[1] = 1;
```

There are use cases for acquiring multiple mutable references to a `slice`, such as for writing independent elements in parallel.
A safe approach is to borrow non-overlapping slices via `slice::split_at_mut`, `slice::chunks_mut`, etc.
However, such approaches may not be applicable in complicated use cases, such as writing to interleaved elements.

### `UnsafeCellSlice`
An `UnsafeCellSlice` can be created from a mutable slice or the spare capacity in a `Vec`.
It has an unsafe `as_mut_slice` method that permits creating multiple mutable `slice` references.

```rust
let mut data = vec![0u8; 2];
{
    let data = UnsafeCellSlice::new(&mut data);
    let data_a: &mut [u8] = unsafe { data.as_mut_slice() };
    let data_b: &mut [u8] = unsafe { data.as_mut_slice() };
    data_a[0] = 0;
    data_b[1] = 1;
}
assert_eq!(data[0], 0);
assert_eq!(data[1], 1);
```

Note that this is very unsafe and bypasses Rust's safety guarantees!
It is the responsibility of the caller of `UnsafeCellSlice::as_mut_slice()` to avoid data races and undefined behavior.

Under the hood, `UnsafeCellSlice` is a reference to a `std::cell::UnsafeCell` slice, hence the name of the crate.

## Licence
`unsafe_cell_slice` is licensed under either of
 - the Apache License, Version 2.0 [LICENSE-APACHE](./LICENCE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0> or
 - the MIT license [LICENSE-MIT](./LICENCE-MIT) or <http://opensource.org/licenses/MIT>, at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.