Module std::borrowUnstable [-]  [+] [src]

A module for working with borrowed data.

The BorrowFrom traits

In general, there may be several ways to "borrow" a piece of data. The typical ways of borrowing a type T are &T (a shared borrow) and &mut T (a mutable borrow). But types like Vec<T> provide additional kinds of borrows: the borrowed slices &[T] and &mut [T].

When writing generic code, it is often desirable to abstract over all ways of borrowing data from a given type. That is the role of the BorrowFrom trait: if T: BorrowFrom<U>, then &T can be borrowed from &U. A given type can be borrowed as multiple different types. In particular, Vec<T>: BorrowFrom<Vec<T>> and [T]: BorrowFrom<Vec<T>>.

The ToOwned trait

Some types make it possible to go from borrowed to owned, usually by implementing the Clone trait. But Clone works only for going from &T to T. The ToOwned trait generalizes Clone to construct owned data from any borrow of a given type.

The Cow (clone-on-write) type

The type Cow is a smart pointer providing clone-on-write functionality: it can enclose and provide immutable access to borrowed data, and clone the data lazily when mutation or ownership is required. The type is designed to work with general borrowed data via the BorrowFrom trait.

Cow implements both Deref, which means that you can call non-mutating methods directly on the data it encloses. If mutation is desired, to_mut will obtain a mutable references to an owned value, cloning if necessary.

Enums

Cow

A clone-on-write smart pointer.

Traits

BorrowFrom

A trait for borrowing data.

BorrowFromMut

A trait for mutably borrowing data.

IntoCow

Trait for moving into a Cow

ToOwned

A generalization of Clone to borrowed data.