Trait sgx_tstd::convert::AsMut

1.0.0 · source ·
pub trait AsMut<T>where
    T: ?Sized,{
    // Required method
    fn as_mut(&mut self) -> &mut T;
}
Expand description

Used to do a cheap mutable-to-mutable reference conversion.

This trait is similar to AsRef but used for converting between mutable references. If you need to do a costly conversion it is better to implement From with type &mut T or write a custom function.

Note: This trait must not fail. If the conversion can fail, use a dedicated method which returns an Option<T> or a Result<T, E>.

Generic Implementations

AsMut auto-dereferences if the inner type is a mutable reference (e.g.: foo.as_mut() will work the same if foo has type &mut Foo or &mut &mut Foo).

Note that due to historic reasons, the above currently does not hold generally for all mutably dereferenceable types, e.g. foo.as_mut() will not work the same as Box::new(foo).as_mut(). Instead, many smart pointers provide an as_mut implementation which simply returns a reference to the pointed-to value (but do not perform a cheap reference-to-reference conversion for that value). However, AsMut::as_mut should not be used for the sole purpose of mutable dereferencing; instead Deref coercion’ can be used:

let mut x = Box::new(5i32);
// Avoid this:
// let y: &mut i32 = x.as_mut();
// Better just write:
let y: &mut i32 = &mut x;

Types which implement DerefMut should consider to add an implementation of AsMut<T> as follows:

impl<T> AsMut<T> for SomeType
where
    <SomeType as Deref>::Target: AsMut<T>,
{
    fn as_mut(&mut self) -> &mut T {
        self.deref_mut().as_mut()
    }
}

Reflexivity

Ideally, AsMut would be reflexive, i.e. there would be an impl<T: ?Sized> AsMut<T> for T with as_mut simply returning its argument unchanged. Such a blanket implementation is currently not provided due to technical restrictions of Rust’s type system (it would be overlapping with another existing blanket implementation for &mut T where T: AsMut<U> which allows AsMut to auto-dereference, see “Generic Implementations” above).

A trivial implementation of AsMut<T> for T must be added explicitly for a particular type T where needed or desired. Note, however, that not all types from std contain such an implementation, and those cannot be added by external code due to orphan rules.

Examples

Using AsMut as trait bound for a generic function, we can accept all mutable references that can be converted to type &mut T. Unlike dereference, which has a single target type, there can be multiple implementations of AsMut for a type. In particular, Vec<T> implements both AsMut<Vec<T>> and AsMut<[T]>.

In the following, the example functions caesar and null_terminate provide a generic interface which work with any type that can be converted by cheap mutable-to-mutable conversion into a byte slice ([u8]) or byte vector (Vec<u8>), respectively.

struct Document {
    info: String,
    content: Vec<u8>,
}

impl<T: ?Sized> AsMut<T> for Document
where
    Vec<u8>: AsMut<T>,
{
    fn as_mut(&mut self) -> &mut T {
        self.content.as_mut()
    }
}

fn caesar<T: AsMut<[u8]>>(data: &mut T, key: u8) {
    for byte in data.as_mut() {
        *byte = byte.wrapping_add(key);
    }
}

fn null_terminate<T: AsMut<Vec<u8>>>(data: &mut T) {
    // Using a non-generic inner function, which contains most of the
    // functionality, helps to minimize monomorphization overhead.
    fn doit(data: &mut Vec<u8>) {
        let len = data.len();
        if len == 0 || data[len-1] != 0 {
            data.push(0);
        }
    }
    doit(data.as_mut());
}

fn main() {
    let mut v: Vec<u8> = vec![1, 2, 3];
    caesar(&mut v, 5);
    assert_eq!(v, [6, 7, 8]);
    null_terminate(&mut v);
    assert_eq!(v, [6, 7, 8, 0]);
    let mut doc = Document {
        info: String::from("Example"),
        content: vec![17, 19, 8],
    };
    caesar(&mut doc, 1);
    assert_eq!(doc.content, [18, 20, 9]);
    null_terminate(&mut doc);
    assert_eq!(doc.content, [18, 20, 9, 0]);
}

Note, however, that APIs don’t need to be generic. In many cases taking a &mut [u8] or &mut Vec<u8>, for example, is the better choice (callers need to pass the correct type then).

Required Methods§

source

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

Implementors§

1.51.0 · source§

impl AsMut<str> for str

1.43.0 · source§

impl AsMut<str> for String

source§

impl AsMut<[u8; 8]> for TeeAttributes

source§

impl AsMut<[u8; 16]> for AlignKey128bit

source§

impl AsMut<[u8; 16]> for AlignMac128bit

source§

impl AsMut<[u8; 16]> for QlQe3Id

source§

impl AsMut<[u8; 16]> for QuoteNonce

source§

impl AsMut<[u8; 16]> for Spid

source§

impl AsMut<[u8; 16]> for TeeCpuSvn

source§

impl AsMut<[u8; 16]> for CpuSvn

source§

impl AsMut<[u8; 16]> for SwitchlessWokerStats

source§

impl AsMut<[u8; 16]> for TeeTcbSvn

source§

impl AsMut<[u8; 20]> for Sha1Hash

source§

impl AsMut<[u8; 32]> for AlignEc256PrivateKey

source§

impl AsMut<[u8; 32]> for AlignEc256SharedKey

source§

impl AsMut<[u8; 32]> for AlignKey256bit

source§

impl AsMut<[u8; 32]> for AlignMac256bit

source§

impl AsMut<[u8; 32]> for Ec256PrivateKey

source§

impl AsMut<[u8; 32]> for Ec256SharedKey

source§

impl AsMut<[u8; 32]> for Sha256Hash

source§

impl AsMut<[u8; 32]> for Sm3Hash

source§

impl AsMut<[u8; 32]> for BaseName

source§

impl AsMut<[u8; 32]> for KeyId

source§

impl AsMut<[u8; 32]> for Measurement

source§

impl AsMut<[u8; 48]> for Sha384Hash

source§

impl AsMut<[u8; 48]> for TeeMeasurement

source§

impl AsMut<[u8; 64]> for Ec256PublicKey

source§

impl AsMut<[u8; 64]> for Ec256Signature

source§

impl AsMut<[u8; 64]> for TeeReportData

source§

impl AsMut<[u8; 64]> for ConfigId

source§

impl AsMut<[u8; 64]> for ReportData

source§

impl AsMut<[u8; 256]> for Rsa2048Signature

source§

impl AsMut<[u8; 260]> for Rsa2048PubKey

source§

impl AsMut<[u8; 384]> for Rsa3072Signature

source§

impl AsMut<[u8; 388]> for Rsa3072PubKey

source§

impl AsMut<[u8; 512]> for Rsa2048PrivKey

source§

impl AsMut<[u8; 516]> for Rsa2048Key

source§

impl AsMut<[u8; 768]> for Rsa3072PrivKey

source§

impl AsMut<[u8; 772]> for Rsa3072Key

source§

impl AsMut<[u8; 1156]> for Rsa2048Param

source§

impl AsMut<[u8; 1732]> for Rsa3072Param

source§

impl AsMut<[u8]> for HeapBuffer

source§

impl AsMut<[u8]> for OcBuffer

source§

impl<T> AsMut<[T]> for [T]

source§

impl<T> AsMut<T> for AlignBox<T>

1.5.0 · source§

impl<T, A> AsMut<[T]> for Vec<T, A>where A: Allocator,

1.5.0 · source§

impl<T, A> AsMut<Vec<T, A>> for Vec<T, A>where A: Allocator,

1.5.0 · source§

impl<T, A> AsMut<T> for Box<T, A>where A: Allocator, T: ?Sized,

source§

impl<T, U> AsMut<U> for &mut Twhere T: AsMut<U> + ?Sized, U: ?Sized,

source§

impl<T, const N: usize> AsMut<[T; N]> for Simd<T, N>where LaneCount<N>: SupportedLaneCount, T: SimdElement,

source§

impl<T, const N: usize> AsMut<[T]> for [T; N]

source§

impl<T, const N: usize> AsMut<[T]> for Simd<T, N>where LaneCount<N>: SupportedLaneCount, T: SimdElement,