multiptr 0.1.0

Maximally convenient and efficient wrapper around a pointer to an element within 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

# multiptr

#### Not production ready. Do not use in production.

[![crates.io](https://img.shields.io/crates/v/multiptr)](https://crates.io/crates/multiptr)
[![docs.rs](https://img.shields.io/docsrs/multiptr)](https://docs.rs/multiptr)

Maximally convenient and efficient wrapper around a pointer to an element within a slice. Allows relative indexing and basic arithmetic. The provided types are akin to [Zig many-item pointers](https://ziglang.org/documentation/master/#Pointers), but come with Rust-specific nuances.

In service of convenience, all operations on the types are marked as safe, even though they conceptually aren't. Otherwise, we'd be locked out of using `Index` and `Deref` traits and their mut friends. To argue for soundness, we require all creation and proliferation of instances of these types to be treated as unsafe.

## Example

```rust
let mut slice = [1, 2, 3, 4, 5];

// Create a pointer to the 3rd element (index 2)
let multi_ptr = unsafe { multiptr::MultiPtr::from_slice_index(&slice, 2) };

// Dereference to get the element
assert_eq!(*multi_ptr, 3);

// Index relative to the pointer
assert_eq!(multi_ptr[1], 4);
assert_eq!(multi_ptr[-1], 2);

// Create a mutable pointer to the 2nd element (index 1)
let mut multi_mut = unsafe { multiptr::MultiMut::from_slice_index(&mut slice, 1) };
assert_eq!(*multi_mut, 2);

// Modify the value through the pointer
*multi_mut = 10;
assert_eq!(multi_mut[0], 10);

// Modify through indexing
multi_mut[2] = 30;
assert_eq!(slice[3], 30);
```