Trait twilio_async::Borrow

pub trait Borrow<Borrowed> where
    Borrowed: ?Sized, {
    fn borrow(&self) -> &Borrowed;
}

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.

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.

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. 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> {
    // fields omitted
}

impl<K, V> HashMap<K, V> {
    pub fn insert(&self, key: K, value: V) -> Option<V>
    where K: Hash + Eq
    {
        // ...
    }

    pub fn get<Q>(&self, k: &Q) -> Option<&V>
    where
        K: Borrow<Q>,
        Q: Hash + Eq + ?Sized
    {
        // ...
    }
}

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:

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.

Required Methods

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &Borrowed

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);

Implementations on Foreign Types

impl Borrow<CStr> for CString

fn borrow(&self) -> &CStr

impl Borrow<Path> for PathBuf

fn borrow(&self) -> &Path

impl Borrow<OsStr> for OsString

fn borrow(&self) -> &OsStr

impl<T> Borrow<[T]> for [T; 20]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 31]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 5]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 2]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 8]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 21]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 7]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<'a, T> Borrow<T> for &'a mut T where     T: ?Sized,

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &T

impl<T> Borrow<[T]> for [T; 6]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 22]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 16]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 32]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 23]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 0]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 3]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 15]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 24]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 11]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 10]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 28]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 19]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 25]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<'a, T> Borrow<T> for &'a T where     T: ?Sized,

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &T

impl<T> Borrow<[T]> for [T; 14]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 12]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 18]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 13]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 26]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 30]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 17]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 1]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 29]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 4]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 9]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<[T]> for [T; 27]

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<T> Borrow<T> for Arc<T> where     T: ?Sized,

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &T

impl<T> Borrow<T> for Box<T> where     T: ?Sized,

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &T

impl<T> Borrow<[T]> for Vec<T>

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[T]

impl<'a, B> Borrow<B> for Cow<'a, B> where     B: ToOwned + ?Sized,     <B as ToOwned>::Owned: 'a,

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &B

impl Borrow<str> for String

fn borrow(&self) -> &str

impl Borrow<[u8]> for BytesMut

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[u8]

impl Borrow<[u8]> for Bytes

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[u8]

impl<T> Borrow<T> for Owned<T>

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn borrow(&self) -> &T

impl<A> Borrow<[<A as Array>::Item]> for ArrayVec<A> where     A: Array,

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[<A as Array>::Item]

impl<A> Borrow<str> for ArrayString<A> where     A: Array<Item = u8>,

fn borrow(&self) -> &str

impl<A> Borrow<[<A as Array>::Item]> for SmallVec<A> where     A: Array,

Important traits for &'a [u8]

impl<'a> Read for &'a [u8]impl<'a> Write for &'a mut [u8]

fn borrow(&self) -> &[<A as Array>::Item]

impl Borrow<X509Ref> for X509

fn borrow(&self) -> &X509Ref

impl Borrow<RsaRef> for Rsa

fn borrow(&self) -> &RsaRef

impl Borrow<ConfRef> for Conf

fn borrow(&self) -> &ConfRef

impl Borrow<SslSessionRef> for SslSession

fn borrow(&self) -> &SslSessionRef

impl Borrow<EcKeyRef> for EcKey

fn borrow(&self) -> &EcKeyRef

impl Borrow<DsaRef> for Dsa

fn borrow(&self) -> &DsaRef

impl Borrow<Asn1ObjectRef> for Asn1Object

fn borrow(&self) -> &Asn1ObjectRef

impl Borrow<EcPointRef> for EcPoint

fn borrow(&self) -> &EcPointRef

impl Borrow<Pkcs12Ref> for Pkcs12

fn borrow(&self) -> &Pkcs12Ref

impl Borrow<X509NameEntryRef> for X509NameEntry

fn borrow(&self) -> &X509NameEntryRef

impl Borrow<X509NameRef> for X509Name

fn borrow(&self) -> &X509NameRef

impl Borrow<OcspBasicResponseRef> for OcspBasicResponse

fn borrow(&self) -> &OcspBasicResponseRef

impl Borrow<OcspCertIdRef> for OcspCertId

fn borrow(&self) -> &OcspCertIdRef

impl Borrow<BigNumRef> for BigNum

fn borrow(&self) -> &BigNumRef

impl Borrow<X509StoreContextRef> for X509StoreContext

fn borrow(&self) -> &X509StoreContextRef

impl Borrow<Asn1BitStringRef> for Asn1BitString

fn borrow(&self) -> &Asn1BitStringRef

impl Borrow<BigNumContextRef> for BigNumContext

fn borrow(&self) -> &BigNumContextRef

impl Borrow<OpensslStringRef> for OpensslString

fn borrow(&self) -> &OpensslStringRef

impl Borrow<CmsContentInfoRef> for CmsContentInfo

fn borrow(&self) -> &CmsContentInfoRef

impl Borrow<X509StoreRef> for X509Store

fn borrow(&self) -> &X509StoreRef

impl<T> Borrow<StackRef<T>> for Stack<T> where     T: Stackable,

fn borrow(&self) -> &StackRef<T>

impl Borrow<GeneralNameRef> for GeneralName

fn borrow(&self) -> &GeneralNameRef

impl Borrow<PKeyCtxRef> for PKeyCtx

fn borrow(&self) -> &PKeyCtxRef

impl Borrow<Asn1IntegerRef> for Asn1Integer

fn borrow(&self) -> &Asn1IntegerRef

impl Borrow<DhRef> for Dh

fn borrow(&self) -> &DhRef

impl Borrow<X509StoreBuilderRef> for X509StoreBuilder

fn borrow(&self) -> &X509StoreBuilderRef

impl Borrow<OcspRequestRef> for OcspRequest

fn borrow(&self) -> &OcspRequestRef

impl Borrow<OcspOneReqRef> for OcspOneReq

fn borrow(&self) -> &OcspOneReqRef

impl Borrow<X509ReqRef> for X509Req

fn borrow(&self) -> &X509ReqRef

impl Borrow<Asn1StringRef> for Asn1String

fn borrow(&self) -> &Asn1StringRef

impl Borrow<SslRef> for Ssl

fn borrow(&self) -> &SslRef

impl Borrow<PKeyRef> for PKey

fn borrow(&self) -> &PKeyRef

impl Borrow<OcspResponseRef> for OcspResponse

fn borrow(&self) -> &OcspResponseRef

impl Borrow<Asn1GeneralizedTimeRef> for Asn1GeneralizedTime

fn borrow(&self) -> &Asn1GeneralizedTimeRef

impl Borrow<EcGroupRef> for EcGroup

fn borrow(&self) -> &EcGroupRef

impl Borrow<X509ExtensionRef> for X509Extension

fn borrow(&self) -> &X509ExtensionRef

impl Borrow<SslContextRef> for SslContext

fn borrow(&self) -> &SslContextRef

impl Borrow<Asn1TimeRef> for Asn1Time

fn borrow(&self) -> &Asn1TimeRef

impl Borrow<X509AlgorithmRef> for X509Algorithm

fn borrow(&self) -> &X509AlgorithmRef

impl Borrow<EcKeyBuilderRef> for EcKeyBuilder

fn borrow(&self) -> &EcKeyBuilderRef

Implementors

• impl<T> Borrow<T> for T where     T: ?Sized,

• impl<T> Borrow<T> for Rc<T> where     T: ?Sized,