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 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 }