src/libcore/borrow.rs - third_party/rust - Git at Google

 //! A module for working with borrowed data.

 #![stable(feature = "rust1", since = "1.0.0")]

 /// A trait for borrowing data.
 ///
 /// In Rust, it is common to provide different representations of a type for
 /// different use cases. For instance, storage location and management for a
 /// value can be specifically chosen as appropriate for a particular use via
 /// pointer types such as [`Box<T>`] or [`Rc<T>`]. Beyond these generic
 /// wrappers that can be used with any type, some types provide optional
 /// facets providing potentially costly functionality. An example for such a
 /// type is [`String`] which adds the ability to extend a string to the basic
 /// [`str`]. This requires keeping additional information unnecessary for a
 /// simple, immutable string.
 ///
 /// These types provide access to the underlying data through references
 /// to the type of that data. They are said to be ‘borrowed as’ that type.
 /// For instance, a [`Box<T>`] can be borrowed as `T` while a [`String`]
 /// can be borrowed as `str`.
 ///
 /// Types express that they can be borrowed as some type `T` by implementing
 /// `Borrow<T>`, providing a reference to a `T` in the trait’s
 /// [`borrow`] method. A type is free to borrow as several different types.
 /// If it wishes to mutably borrow as the type – allowing the underlying data
 /// to be modified, it can additionally implement [`BorrowMut<T>`].
 ///
 /// Further, when providing implementations for additional traits, it needs
 /// to be considered whether they should behave identical to those of the
 /// underlying type as a consequence of acting as a representation of that
 /// underlying type. Generic code typically uses `Borrow<T>` when it relies
 /// on the identical behavior of these additional trait implementations.
 /// These traits will likely appear as additional trait bounds.
 ///
 /// In particular `Eq`, `Ord` and `Hash` must be equivalent for
 /// borrowed and owned values: `x.borrow() == y.borrow()` should give the
 /// same result as `x == y`.
 ///
 /// If generic code merely needs to work for all types that can
 /// provide a reference to related type `T`, it is often better to use
 /// [`AsRef<T>`] as more types can safely implement it.
 ///
 /// [`AsRef<T>`]: ../../std/convert/trait.AsRef.html
 /// [`BorrowMut<T>`]: trait.BorrowMut.html
 /// [`Box<T>`]: ../../std/boxed/struct.Box.html
 /// [`Mutex<T>`]: ../../std/sync/struct.Mutex.html
 /// [`Rc<T>`]: ../../std/rc/struct.Rc.html
 /// [`str`]: ../../std/primitive.str.html
 /// [`String`]: ../../std/string/struct.String.html
 /// [`borrow`]: #tymethod.borrow
 ///
 /// # Examples
 ///
 /// As a data collection, [`HashMap<K, V>`] owns both keys and values. If
 /// the key’s actual data is wrapped in a managing type of some kind, it
 /// should, however, still be possible to search for a value using a
 /// reference to the key’s data. For instance, if the key is a string, then
 /// it is likely stored with the hash map as a [`String`], while it should
 /// be possible to search using a [`&str`][`str`]. Thus, `insert` needs to
 /// operate on a `String` while `get` needs to be able to use a `&str`.
 ///
 /// Slightly simplified, the relevant parts of `HashMap<K, V>` look like
 /// this:
 ///
 /// ```
 /// use std::borrow::Borrow;
 /// use std::hash::Hash;
 ///
 /// pub struct HashMap<K, V> {
 ///     # marker: ::std::marker::PhantomData<(K, V)>,
 ///     // fields omitted
 /// }
 ///
 /// impl<K, V> HashMap<K, V> {
 ///     pub fn insert(&self, key: K, value: V) -> Option<V>
 ///     where K: Hash + Eq
 ///     {
 ///         # unimplemented!()
 ///         // ...
 ///     }
 ///
 ///     pub fn get<Q>(&self, k: &Q) -> Option<&V>
 ///     where
 ///         K: Borrow<Q>,
 ///         Q: Hash + Eq + ?Sized
 ///     {
 ///         # unimplemented!()
 ///         // ...
 ///     }
 /// }
 /// ```
 ///
 /// The entire hash map is generic over a key type `K`. Because these keys
 /// are stored with the hash map, this type has to own the key’s data.
 /// When inserting a key-value pair, the map is given such a `K` and needs
 /// to find the correct hash bucket and check if the key is already present
 /// based on that `K`. It therefore requires `K: Hash + Eq`.
 ///
 /// When searching for a value in the map, however, having to provide a
 /// reference to a `K` as the key to search for would require to always
 /// create such an owned value. For string keys, this would mean a `String`
 /// value needs to be created just for the search for cases where only a
 /// `str` is available.
 ///
 /// Instead, the `get` method is generic over the type of the underlying key
 /// data, called `Q` in the method signature above. It states that `K`
 /// borrows as a `Q` by requiring that `K: Borrow<Q>`. By additionally
 /// requiring `Q: Hash + Eq`, it signals the requirement that `K` and `Q`
 /// have implementations of the `Hash` and `Eq` traits that produce identical
 /// results.
 ///
 /// The implementation of `get` relies in particular on identical
 /// implementations of `Hash` by determining the key’s hash bucket by calling
 /// `Hash::hash` on the `Q` value even though it inserted the key based on
 /// the hash value calculated from the `K` value.
 ///
 /// As a consequence, the hash map breaks if a `K` wrapping a `Q` value
 /// produces a different hash than `Q`. For instance, imagine you have a
 /// type that wraps a string but compares ASCII letters ignoring their case:
 ///
 /// ```
 /// pub struct CaseInsensitiveString(String);
 ///
 /// impl PartialEq for CaseInsensitiveString {
 ///     fn eq(&self, other: &Self) -> bool {
 ///         self.0.eq_ignore_ascii_case(&other.0)
 ///     }
 /// }
 ///
 /// impl Eq for CaseInsensitiveString { }
 /// ```
 ///
 /// Because two equal values need to produce the same hash value, the
 /// implementation of `Hash` needs to ignore ASCII case, too:
 ///
 /// ```
 /// # use std::hash::{Hash, Hasher};
 /// # pub struct CaseInsensitiveString(String);
 /// impl Hash for CaseInsensitiveString {
 ///     fn hash<H: Hasher>(&self, state: &mut H) {
 ///         for c in self.0.as_bytes() {
 ///             c.to_ascii_lowercase().hash(state)
 ///         }
 ///     }
 /// }
 /// ```
 ///
 /// Can `CaseInsensitiveString` implement `Borrow<str>`? It certainly can
 /// provide a reference to a string slice via its contained owned string.
 /// But because its `Hash` implementation differs, it behaves differently
 /// from `str` and therefore must not, in fact, implement `Borrow<str>`.
 /// If it wants to allow others access to the underlying `str`, it can do
 /// that via `AsRef<str>` which doesn’t carry any extra requirements.
 ///
 /// [`Hash`]: ../../std/hash/trait.Hash.html
 /// [`HashMap<K, V>`]: ../../std/collections/struct.HashMap.html
 /// [`String`]: ../../std/string/struct.String.html
 /// [`str`]: ../../std/primitive.str.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.
 ///
 /// As a companion to [`Borrow<T>`] this trait allows a type to borrow as
 /// an underlying type by providing a mutable reference. See [`Borrow<T>`]
 /// for more information on borrowing as another type.
 ///
 /// [`Borrow<T>`]: trait.Borrow.html
 #[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<T: ?Sized> Borrow<T> for &T {
     fn borrow(&self) -> &T {
         &**self
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Borrow<T> for &mut T {
     fn borrow(&self) -> &T {
         &**self
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> BorrowMut<T> for &mut T {
     fn borrow_mut(&mut self) -> &mut T {
         &mut **self
     }
 }
	//! A module for working with borrowed data.

	#![stable(feature = "rust1", since = "1.0.0")]

	/// A trait for borrowing data.
	///
	/// In Rust, it is common to provide different representations of a type for
	/// different use cases. For instance, storage location and management for a
	/// value can be specifically chosen as appropriate for a particular use via
	/// pointer types such as [`Box<T>`] or [`Rc<T>`]. Beyond these generic
	/// wrappers that can be used with any type, some types provide optional
	/// facets providing potentially costly functionality. An example for such a
	/// type is [`String`] which adds the ability to extend a string to the basic
	/// [`str`]. This requires keeping additional information unnecessary for a
	/// simple, immutable string.
	///
	/// These types provide access to the underlying data through references
	/// to the type of that data. They are said to be ‘borrowed as’ that type.
	/// For instance, a [`Box<T>`] can be borrowed as `T` while a [`String`]
	/// can be borrowed as `str`.
	///
	/// Types express that they can be borrowed as some type `T` by implementing
	/// `Borrow<T>`, providing a reference to a `T` in the trait’s
	/// [`borrow`] method. A type is free to borrow as several different types.
	/// If it wishes to mutably borrow as the type – allowing the underlying data
	/// to be modified, it can additionally implement [`BorrowMut<T>`].
	///
	/// Further, when providing implementations for additional traits, it needs
	/// to be considered whether they should behave identical to those of the
	/// underlying type as a consequence of acting as a representation of that
	/// underlying type. Generic code typically uses `Borrow<T>` when it relies
	/// on the identical behavior of these additional trait implementations.
	/// These traits will likely appear as additional trait bounds.
	///
	/// In particular `Eq`, `Ord` and `Hash` must be equivalent for
	/// borrowed and owned values: `x.borrow() == y.borrow()` should give the
	/// same result as `x == y`.
	///
	/// If generic code merely needs to work for all types that can
	/// provide a reference to related type `T`, it is often better to use
	/// [`AsRef<T>`] as more types can safely implement it.
	///
	/// [`AsRef<T>`]: ../../std/convert/trait.AsRef.html
	/// [`BorrowMut<T>`]: trait.BorrowMut.html
	/// [`Box<T>`]: ../../std/boxed/struct.Box.html
	/// [`Mutex<T>`]: ../../std/sync/struct.Mutex.html
	/// [`Rc<T>`]: ../../std/rc/struct.Rc.html
	/// [`str`]: ../../std/primitive.str.html
	/// [`String`]: ../../std/string/struct.String.html
	/// [`borrow`]: #tymethod.borrow
	///
	/// # Examples
	///
	/// As a data collection, [`HashMap<K, V>`] owns both keys and values. If
	/// the key’s actual data is wrapped in a managing type of some kind, it
	/// should, however, still be possible to search for a value using a
	/// reference to the key’s data. For instance, if the key is a string, then
	/// it is likely stored with the hash map as a [`String`], while it should
	/// be possible to search using a [`&str`][`str`]. Thus, `insert` needs to
	/// operate on a `String` while `get` needs to be able to use a `&str`.
	///
	/// Slightly simplified, the relevant parts of `HashMap<K, V>` look like
	/// this:
	///
	/// ```
	/// use std::borrow::Borrow;
	/// use std::hash::Hash;
	///
	/// pub struct HashMap<K, V> {
	/// # marker: ::std::marker::PhantomData<(K, V)>,
	/// // fields omitted
	/// }
	///
	/// impl<K, V> HashMap<K, V> {
	/// pub fn insert(&self, key: K, value: V) -> Option<V>
	/// where K: Hash + Eq
	/// {
	/// # unimplemented!()
	/// // ...
	/// }
	///
	/// pub fn get<Q>(&self, k: &Q) -> Option<&V>
	/// where
	/// K: Borrow<Q>,
	/// Q: Hash + Eq + ?Sized
	/// {
	/// # unimplemented!()
	/// // ...
	/// }
	/// }
	/// ```
	///
	/// The entire hash map is generic over a key type `K`. Because these keys
	/// are stored with the hash map, this type has to own the key’s data.
	/// When inserting a key-value pair, the map is given such a `K` and needs
	/// to find the correct hash bucket and check if the key is already present
	/// based on that `K`. It therefore requires `K: Hash + Eq`.
	///
	/// When searching for a value in the map, however, having to provide a
	/// reference to a `K` as the key to search for would require to always
	/// create such an owned value. For string keys, this would mean a `String`
	/// value needs to be created just for the search for cases where only a
	/// `str` is available.
	///
	/// Instead, the `get` method is generic over the type of the underlying key
	/// data, called `Q` in the method signature above. It states that `K`
	/// borrows as a `Q` by requiring that `K: Borrow<Q>`. By additionally
	/// requiring `Q: Hash + Eq`, it signals the requirement that `K` and `Q`
	/// have implementations of the `Hash` and `Eq` traits that produce identical
	/// results.
	///
	/// The implementation of `get` relies in particular on identical
	/// implementations of `Hash` by determining the key’s hash bucket by calling
	/// `Hash::hash` on the `Q` value even though it inserted the key based on
	/// the hash value calculated from the `K` value.
	///
	/// As a consequence, the hash map breaks if a `K` wrapping a `Q` value
	/// produces a different hash than `Q`. For instance, imagine you have a
	/// type that wraps a string but compares ASCII letters ignoring their case:
	///
	/// ```
	/// pub struct CaseInsensitiveString(String);
	///
	/// impl PartialEq for CaseInsensitiveString {
	/// fn eq(&self, other: &Self) -> bool {
	/// self.0.eq_ignore_ascii_case(&other.0)
	/// }
	/// }
	///
	/// impl Eq for CaseInsensitiveString { }
	/// ```
	///
	/// Because two equal values need to produce the same hash value, the
	/// implementation of `Hash` needs to ignore ASCII case, too:
	///
	/// ```
	/// # use std::hash::{Hash, Hasher};
	/// # pub struct CaseInsensitiveString(String);
	/// impl Hash for CaseInsensitiveString {
	/// fn hash<H: Hasher>(&self, state: &mut H) {
	/// for c in self.0.as_bytes() {
	/// c.to_ascii_lowercase().hash(state)
	/// }
	/// }
	/// }
	/// ```
	///
	/// Can `CaseInsensitiveString` implement `Borrow<str>`? It certainly can
	/// provide a reference to a string slice via its contained owned string.
	/// But because its `Hash` implementation differs, it behaves differently
	/// from `str` and therefore must not, in fact, implement `Borrow<str>`.
	/// If it wants to allow others access to the underlying `str`, it can do
	/// that via `AsRef<str>` which doesn’t carry any extra requirements.
	///
	/// [`Hash`]: ../../std/hash/trait.Hash.html
	/// [`HashMap<K, V>`]: ../../std/collections/struct.HashMap.html
	/// [`String`]: ../../std/string/struct.String.html
	/// [`str`]: ../../std/primitive.str.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.
	///
	/// As a companion to [`Borrow<T>`] this trait allows a type to borrow as
	/// an underlying type by providing a mutable reference. See [`Borrow<T>`]
	/// for more information on borrowing as another type.
	///
	/// [`Borrow<T>`]: trait.Borrow.html
	#[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<T: ?Sized> Borrow<T> for &T {
	fn borrow(&self) -> &T {
	&**self
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> Borrow<T> for &mut T {
	fn borrow(&self) -> &T {
	&**self
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> BorrowMut<T> for &mut T {
	fn borrow_mut(&mut self) -> &mut T {
	&mut **self
	}
	}