#reference #field #sibling #owning

owning_ref

A library for creating references that carry their owner with them

15 releases

0.4.0 Aug 17, 2018
0.3.3 Mar 9, 2017
0.2.4 Jan 16, 2017
0.2.2 Oct 7, 2016
0.1.2 Jul 27, 2015

#5 in Rust patterns

Download history 14993/week @ 2018-08-21 26661/week @ 2018-08-28 30548/week @ 2018-09-04 31829/week @ 2018-09-11 33505/week @ 2018-09-18 32997/week @ 2018-09-25 36834/week @ 2018-10-02 42353/week @ 2018-10-09 39591/week @ 2018-10-16 37339/week @ 2018-10-23 43645/week @ 2018-10-30 44103/week @ 2018-11-06 35839/week @ 2018-11-13

73,230 downloads per month
Used in 227 crates (21 directly)

MIT license

64KB
1K SLoC

owning-ref-rs

A library for creating references that carry their owner with them.

This can sometimes be useful because Rust borrowing rules normally prevent moving a type that has been borrowed from. For example, this kind of code gets rejected:

fn return_owned_and_referenced<'a>() -> (Vec<u8>, &'a [u8]) {
    let v = vec![1, 2, 3, 4];
    let s = &v[1..3];
    (v, s)
}

This library enables this safe usage by keeping the owner and the reference bundled together in a wrapper type that ensure that lifetime constraint:

fn return_owned_and_referenced() -> OwningRef<Vec<u8>, [u8]> {
    let v = vec![1, 2, 3, 4];
    let or = OwningRef::new(v);
    let or = or.map(|v| &v[1..3]);
    or
}

Travis-CI Status

Getting Started

owning-ref-rs is available on crates.io. It is recommended to look there for the newest released version, as well as links to the newest builds of the docs.

At the point of the last update of this README, the latest published version could be used like this:

Add the following dependency to your Cargo manifest...

[dependencies]
owning_ref = "0.3"

...and see the docs for how to use it.

Example

extern crate owning_ref;
use owning_ref::BoxRef;

fn main() {
    // Create an array owned by a Box.
    let arr = Box::new([1, 2, 3, 4]) as Box<[i32]>;

    // Transfer into a BoxRef.
    let arr: BoxRef<[i32]> = BoxRef::new(arr);
    assert_eq!(&*arr, &[1, 2, 3, 4]);

    // We can slice the array without losing ownership or changing type.
    let arr: BoxRef<[i32]> = arr.map(|arr| &arr[1..3]);
    assert_eq!(&*arr, &[2, 3]);

    // Also works for Arc, Rc, String and Vec!
}

Dependencies

~12KB