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[![Travis-CI Status](https://travis-ci.org/Kimundi/owning-ref-rs.png?branch=master)](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