1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
// Copyright 2014 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! A module for working with borrowed data. #![stable(feature = "rust1", since = "1.0.0")] /// A trait for borrowing data. /// /// 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 `Borrow` /// trait: if `T: Borrow<U>`, then `&U` can be borrowed from `&T`. A given /// type can be borrowed as multiple different types. In particular, `Vec<T>: /// Borrow<Vec<T>>` and `Vec<T>: Borrow<[T]>`. /// /// If you are implementing `Borrow` and both `Self` and `Borrowed` implement /// `Hash`, `Eq`, and/or `Ord`, they must produce the same result. /// /// `Borrow` is very similar to, but different than, `AsRef`. See /// [the book][book] for more. /// /// [book]: ../../book/first-edition/borrow-and-asref.html #[stable(feature = "rust1", since = "1.0.0")] pub trait Borrow<Borrowed: ?Sized> { /// Immutably borrows from an owned value. /// /// # Examples /// /// ``` /// use std::borrow::Borrow; /// /// fn check<T: Borrow<str>>(s: T) { /// assert_eq!("Hello", s.borrow()); /// } /// /// let s = "Hello".to_string(); /// /// check(s); /// /// let s = "Hello"; /// /// check(s); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn borrow(&self) -> &Borrowed; } /// A trait for mutably borrowing data. /// /// Similar to `Borrow`, but for mutable borrows. #[stable(feature = "rust1", since = "1.0.0")] pub trait BorrowMut<Borrowed: ?Sized> : Borrow<Borrowed> { /// Mutably borrows from an owned value. /// /// # Examples /// /// ``` /// use std::borrow::BorrowMut; /// /// fn check<T: BorrowMut<[i32]>>(mut v: T) { /// assert_eq!(&mut [1, 2, 3], v.borrow_mut()); /// } /// /// let v = vec![1, 2, 3]; /// /// check(v); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn borrow_mut(&mut self) -> &mut Borrowed; } #[stable(feature = "rust1", since = "1.0.0")] impl<T: ?Sized> Borrow<T> for T { fn borrow(&self) -> &T { self } } #[stable(feature = "rust1", since = "1.0.0")] impl<T: ?Sized> BorrowMut<T> for T { fn borrow_mut(&mut self) -> &mut T { self } } #[stable(feature = "rust1", since = "1.0.0")] impl<'a, T: ?Sized> Borrow<T> for &'a T { fn borrow(&self) -> &T { &**self } } #[stable(feature = "rust1", since = "1.0.0")] impl<'a, T: ?Sized> Borrow<T> for &'a mut T { fn borrow(&self) -> &T { &**self } } #[stable(feature = "rust1", since = "1.0.0")] impl<'a, T: ?Sized> BorrowMut<T> for &'a mut T { fn borrow_mut(&mut self) -> &mut T { &mut **self } }