1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! A module for working with borrowed data.
13 #![stable(feature = "rust1", since = "1.0.0")]
15 /// A trait for borrowing data.
17 /// In general, there may be several ways to "borrow" a piece of data. The
18 /// typical ways of borrowing a type `T` are `&T` (a shared borrow) and `&mut T`
19 /// (a mutable borrow). But types like `Vec<T>` provide additional kinds of
20 /// borrows: the borrowed slices `&[T]` and `&mut [T]`.
22 /// When writing generic code, it is often desirable to abstract over all ways
23 /// of borrowing data from a given type. That is the role of the `Borrow`
24 /// trait: if `T: Borrow<U>`, then `&U` can be borrowed from `&T`. A given
25 /// type can be borrowed as multiple different types. In particular, `Vec<T>:
26 /// Borrow<Vec<T>>` and `Vec<T>: Borrow<[T]>`.
28 /// If you are implementing `Borrow` and both `Self` and `Borrowed` implement
29 /// `Hash`, `Eq`, and/or `Ord`, they must produce the same result.
31 /// `Borrow` is very similar to, but different than, `AsRef`. See
32 /// [the book][book] for more.
34 /// [book]: ../../book/first-edition/borrow-and-asref.html
35 #[stable(feature = "rust1", since = "1.0.0")]
36 pub trait Borrow<Borrowed: ?Sized> {
37 /// Immutably borrows from an owned value.
42 /// use std::borrow::Borrow;
44 /// fn check<T: Borrow<str>>(s: T) {
45 /// assert_eq!("Hello", s.borrow());
48 /// let s = "Hello".to_string();
56 #[stable(feature = "rust1", since = "1.0.0")]
57 fn borrow(&self) -> &Borrowed;
60 /// A trait for mutably borrowing data.
62 /// Similar to `Borrow`, but for mutable borrows.
63 #[stable(feature = "rust1", since = "1.0.0")]
64 pub trait BorrowMut<Borrowed: ?Sized> : Borrow<Borrowed> {
65 /// Mutably borrows from an owned value.
70 /// use std::borrow::BorrowMut;
72 /// fn check<T: BorrowMut<[i32]>>(mut v: T) {
73 /// assert_eq!(&mut [1, 2, 3], v.borrow_mut());
76 /// let v = vec![1, 2, 3];
80 #[stable(feature = "rust1", since = "1.0.0")]
81 fn borrow_mut(&mut self) -> &mut Borrowed;
84 #[stable(feature = "rust1", since = "1.0.0")]
85 impl<T: ?Sized> Borrow<T> for T {
86 fn borrow(&self) -> &T { self }
89 #[stable(feature = "rust1", since = "1.0.0")]
90 impl<T: ?Sized> BorrowMut<T> for T {
91 fn borrow_mut(&mut self) -> &mut T { self }
94 #[stable(feature = "rust1", since = "1.0.0")]
95 impl<'a, T: ?Sized> Borrow<T> for &'a T {
96 fn borrow(&self) -> &T { &**self }
99 #[stable(feature = "rust1", since = "1.0.0")]
100 impl<'a, T: ?Sized> Borrow<T> for &'a mut T {
101 fn borrow(&self) -> &T { &**self }
104 #[stable(feature = "rust1", since = "1.0.0")]
105 impl<'a, T: ?Sized> BorrowMut<T> for &'a mut T {
106 fn borrow_mut(&mut self) -> &mut T { &mut **self }