core/borrow.rs
1//! Utilities for working with borrowed data.
2
3#![stable(feature = "rust1", since = "1.0.0")]
4
5/// A trait for borrowing data.
6///
7/// In Rust, it is common to provide different representations of a type for
8/// different use cases. For instance, storage location and management for a
9/// value can be specifically chosen as appropriate for a particular use via
10/// pointer types such as [`Box<T>`] or [`Rc<T>`]. Beyond these generic
11/// wrappers that can be used with any type, some types provide optional
12/// facets providing potentially costly functionality. An example for such a
13/// type is [`String`] which adds the ability to extend a string to the basic
14/// [`str`]. This requires keeping additional information unnecessary for a
15/// simple, immutable string.
16///
17/// These types provide access to the underlying data through references
18/// to the type of that data. They are said to be ‘borrowed as’ that type.
19/// For instance, a [`Box<T>`] can be borrowed as `T` while a [`String`]