src/libcore/borrow.rs

   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 /// A trait for borrowing data.
  16 ///
  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]`.
  21 ///
  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]>`.
  27 ///
  28 /// If you are implementing `Borrow` and both `Self` and `Borrowed` implement
  29 /// `Hash`, `Eq`, and/or `Ord`, they must produce the same result.
  30 ///
  31 /// `Borrow` is very similar to, but different than, `AsRef`. See
  32 /// [the book][book] for more.
  33 ///
  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.
  38     ///
  39     /// # Examples
  40     ///
  41     /// ```
  42     /// use std::borrow::Borrow;
  43     ///
  44     /// fn check<T: Borrow<str>>(s: T) {
  45     ///     assert_eq!("Hello", s.borrow());
  46     /// }
  47     ///
  48     /// let s = "Hello".to_string();
  49     ///
  50     /// check(s);
  51     ///
  52     /// let s = "Hello";
  53     ///
  54     /// check(s);
  55     /// ```
  56     #[stable(feature = "rust1", since = "1.0.0")]
  57     fn borrow(&self) -> &Borrowed;
  58 }
  59
  60 /// A trait for mutably borrowing data.
  61 ///
  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.
  66     ///
  67     /// # Examples
  68     ///
  69     /// ```
  70     /// use std::borrow::BorrowMut;
  71     ///
  72     /// fn check<T: BorrowMut<[i32]>>(mut v: T) {
  73     ///     assert_eq!(&mut [1, 2, 3], v.borrow_mut());
  74     /// }
  75     ///
  76     /// let v = vec![1, 2, 3];
  77     ///
  78     /// check(v);
  79     /// ```
  80     #[stable(feature = "rust1", since = "1.0.0")]
  81     fn borrow_mut(&mut self) -> &mut Borrowed;
  82 }
  83
  84 #[stable(feature = "rust1", since = "1.0.0")]
  85 impl<T: ?Sized> Borrow<T> for T {
  86     fn borrow(&self) -> &T { self }
  87 }
  88
  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 }
  92 }
  93
  94 #[stable(feature = "rust1", since = "1.0.0")]
  95 impl<'a, T: ?Sized> Borrow<T> for &'a T {
  96     fn borrow(&self) -> &T { &**self }
  97 }
  98
  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 }
 102 }
 103
 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 }
 107 }