]>
Commit | Line | Data |
---|---|---|
e9174d1e SL |
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. | |
4 | // | |
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. | |
10 | ||
11 | //! A module for working with borrowed data. | |
12 | ||
13 | #![stable(feature = "rust1", since = "1.0.0")] | |
14 | ||
15 | use marker::Sized; | |
16 | ||
17 | /// A trait for borrowing data. | |
18 | /// | |
19 | /// In general, there may be several ways to "borrow" a piece of data. The | |
20 | /// typical ways of borrowing a type `T` are `&T` (a shared borrow) and `&mut T` | |
21 | /// (a mutable borrow). But types like `Vec<T>` provide additional kinds of | |
22 | /// borrows: the borrowed slices `&[T]` and `&mut [T]`. | |
23 | /// | |
24 | /// When writing generic code, it is often desirable to abstract over all ways | |
25 | /// of borrowing data from a given type. That is the role of the `Borrow` | |
26 | /// trait: if `T: Borrow<U>`, then `&U` can be borrowed from `&T`. A given | |
27 | /// type can be borrowed as multiple different types. In particular, `Vec<T>: | |
28 | /// Borrow<Vec<T>>` and `Vec<T>: Borrow<[T]>`. | |
29 | /// | |
30 | /// If you are implementing `Borrow` and both `Self` and `Borrowed` implement | |
31 | /// `Hash`, `Eq`, and/or `Ord`, they must produce the same result. | |
32 | /// | |
33 | /// `Borrow` is very similar to, but different than, `AsRef`. See | |
34 | /// [the book][book] for more. | |
35 | /// | |
36 | /// [book]: ../../book/borrow-and-asref.html | |
37 | #[stable(feature = "rust1", since = "1.0.0")] | |
38 | pub trait Borrow<Borrowed: ?Sized> { | |
39 | /// Immutably borrows from an owned value. | |
40 | /// | |
41 | /// # Examples | |
42 | /// | |
43 | /// ``` | |
44 | /// use std::borrow::Borrow; | |
45 | /// | |
46 | /// fn check<T: Borrow<str>>(s: T) { | |
47 | /// assert_eq!("Hello", s.borrow()); | |
48 | /// } | |
49 | /// | |
50 | /// let s = "Hello".to_string(); | |
51 | /// | |
52 | /// check(s); | |
53 | /// | |
54 | /// let s = "Hello"; | |
55 | /// | |
56 | /// check(s); | |
57 | /// ``` | |
58 | #[stable(feature = "rust1", since = "1.0.0")] | |
59 | fn borrow(&self) -> &Borrowed; | |
60 | } | |
61 | ||
62 | /// A trait for mutably borrowing data. | |
63 | /// | |
64 | /// Similar to `Borrow`, but for mutable borrows. | |
65 | #[stable(feature = "rust1", since = "1.0.0")] | |
66 | pub trait BorrowMut<Borrowed: ?Sized> : Borrow<Borrowed> { | |
67 | /// Mutably borrows from an owned value. | |
68 | /// | |
69 | /// # Examples | |
70 | /// | |
71 | /// ``` | |
72 | /// use std::borrow::BorrowMut; | |
73 | /// | |
74 | /// fn check<T: BorrowMut<[i32]>>(mut v: T) { | |
75 | /// assert_eq!(&mut [1, 2, 3], v.borrow_mut()); | |
76 | /// } | |
77 | /// | |
78 | /// let v = vec![1, 2, 3]; | |
79 | /// | |
80 | /// check(v); | |
81 | /// ``` | |
82 | #[stable(feature = "rust1", since = "1.0.0")] | |
83 | fn borrow_mut(&mut self) -> &mut Borrowed; | |
84 | } | |
85 | ||
86 | #[stable(feature = "rust1", since = "1.0.0")] | |
87 | impl<T: ?Sized> Borrow<T> for T { | |
88 | fn borrow(&self) -> &T { self } | |
89 | } | |
90 | ||
91 | #[stable(feature = "rust1", since = "1.0.0")] | |
92 | impl<T: ?Sized> BorrowMut<T> for T { | |
93 | fn borrow_mut(&mut self) -> &mut T { self } | |
94 | } | |
95 | ||
96 | #[stable(feature = "rust1", since = "1.0.0")] | |
97 | impl<'a, T: ?Sized> Borrow<T> for &'a T { | |
98 | fn borrow(&self) -> &T { &**self } | |
99 | } | |
100 | ||
101 | #[stable(feature = "rust1", since = "1.0.0")] | |
102 | impl<'a, T: ?Sized> Borrow<T> for &'a mut T { | |
103 | fn borrow(&self) -> &T { &**self } | |
104 | } | |
105 | ||
106 | #[stable(feature = "rust1", since = "1.0.0")] | |
107 | impl<'a, T: ?Sized> BorrowMut<T> for &'a mut T { | |
108 | fn borrow_mut(&mut self) -> &mut T { &mut **self } | |
109 | } |