README.md
1owning-ref-rs
2==============
3
4A library for creating references that carry their owner with them.
5
6This can sometimes be useful because Rust borrowing rules normally prevent
7moving a type that has been borrowed from. For example, this kind of code gets rejected:
8
9```rust
10fn return_owned_and_referenced<'a>() -> (Vec<u8>, &'a [u8]) {
11 let v = vec![1, 2, 3, 4];
12 let s = &v[1..3];
13 (v, s)
14}
15```
16
17This library enables this safe usage by keeping the owner and the reference
18bundled together in a wrapper type that ensure that lifetime constraint:
19
20```rust
21fn return_owned_and_referenced() -> OwningRef<Vec<u8>, [u8]> {
22 let v = vec![1, 2, 3, 4];
23 let or = OwningRef::new(v);
24 let or = or.map(|v| &v[1..3]);
25 or
26}
27```
28
29[](https://travis-ci.org/Kimundi/owning-ref-rs)
30
31# Getting Started
32
33[owning-ref-rs is available on crates.io](https://crates.io/crates/owning_ref).
34It is recommended to look there for the newest released version, as well as links to the newest builds of the docs.
35
36At the point of the last update of this README, the latest published version could be used like this:
37
38Add the following dependency to your Cargo manifest...
39
40```toml
41[dependencies]
42owning_ref = "0.3"
43```
44
45...and see the [docs](http://kimundi.github.io/owning-ref-rs/owning_ref/index.html) for how to use it.
46
47# Example
48
49```rust
50extern crate owning_ref;
51use owning_ref::BoxRef;
52
53fn main() {
54 // Create an array owned by a Box.
55 let arr = Box::new([1, 2, 3, 4]) as Box<[i32]>;
56
57 // Transfer into a BoxRef.
58 let arr: BoxRef<[i32]> = BoxRef::new(arr);
59 assert_eq!(&*arr, &[1, 2, 3, 4]);
60
61 // We can slice the array without losing ownership or changing type.
62 let arr: BoxRef<[i32]> = arr.map(|arr| &arr[1..3]);
63 assert_eq!(&*arr, &[2, 3]);
64
65 // Also works for Arc, Rc, String and Vec!
66}
67```
68
){kind=link}