third_party/rust/owning_ref/README.md
author Razvan Caliman <rcaliman@mozilla.com>
Mon, 25 Feb 2019 22:20:53 +0000
changeset 518875 f5629bb3e671ad15ede908de3cc0b2b2be342728
parent 509777 28134941aac4065784b991962cad17f9ac71208d
permissions -rw-r--r--
Bug 1529606 - Add Copy Rule button to Changes panel. r=pbro Adds a button that shows up when hovering selectors in the Changes panel. When clicked, it invokes the same Copy Rule behavior implemented for the context menu: copies the full content of the rule with changes applied. The added/changed CSS class names use BEM notation. I intend to refactor the Changes panel stylesheet to BEM in a follow-up patch. Differential Revision: https://phabricator.services.mozilla.com/D20808

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:

```rust
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:

```rust
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](https://travis-ci.org/Kimundi/owning-ref-rs.png?branch=master)](https://travis-ci.org/Kimundi/owning-ref-rs)

# Getting Started

[owning-ref-rs is available on crates.io](https://crates.io/crates/owning_ref).
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...

```toml
[dependencies]
owning_ref = "0.3"
```

...and see the [docs](http://kimundi.github.io/owning-ref-rs/owning_ref/index.html) for how to use it.

# Example

```rust
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!
}
```