devela/sys/mem/
ext.rs

Help
1// devela::sys::mem::ext
2//
3//! Defines [`ExtMem`], An extension trait for memory management over `T`.
4//
5
6use super::Mem;
7
8impl<T: ?Sized> ExtMem for T {}
9
10#[doc = crate::TAG_NAMESPACE!()]
11/// Extension trait for type memory information and manipulation.
12///
13/// This trait is automatically implemented for every `?Sized` type,
14/// although most methods are only available where `Self: Sized`.
15#[rustfmt::skip]
16pub trait ExtMem {
17    /// Know whether dropping values of this type matters, in compile-time.
18    const NEEDS_DROP: bool = Mem::needs_drop::<Self>();
19
20    /// Returns the minimum alignment of the type in bytes.
21    ///
22    /// See [`Mem::align_of`].
23    #[must_use]
24    fn mem_align_of<T>() -> usize { Mem::align_of::<T>() }
25
26    /// Returns the alignment of the pointed-to value in bytes.
27    ///
28    /// See [`Mem::align_of_val`].
29    #[must_use]
30    fn mem_align_of_val(&self) -> usize { Mem::align_of_val(self) }
31
32    /// Returns the size of a type in bytes.
33    ///
34    /// See [`Mem::size_of`].
35    #[must_use]
36    fn mem_size_of<T>() -> usize { Mem::size_of::<T>() }
37
38    /// Returns the size of the pointed-to value in bytes.
39    ///
40    /// See [`Mem::size_of_val`].
41    #[must_use]
42    fn mem_size_of_val(&self) -> usize { Mem::size_of_val(self) }
43
44    /// Bitwise-copies a value.
45    ///
46    /// It is useful when you want to pass a function pointer to a combinator,
47    /// rather than defining a new closure.
48    ///
49    /// See [`Mem::copy`].
50    #[must_use]
51    fn mem_copy(&self) -> Self where Self: Copy { Mem::copy(self) }
52
53    /// Returns `true` if dropping values of this type matters.
54    ///
55    /// See [`Mem::needs_drop`].
56    #[must_use]
57    fn mem_needs_drop(&self) -> bool { Self::NEEDS_DROP }
58
59    /// Drops `self` by running its destructor.
60    ///
61    /// See [`Mem::drop`].
62    fn mem_drop(self) where Self: Sized { Mem::drop(self) }
63
64    /// Forgets about `self` *without running its destructor*.
65    ///
66    /// See [`Mem::forget`].
67    fn mem_forget(self) where Self: Sized { Mem::forget(self) }
68
69    /// Replaces `self` with other, returning the previous value of `self`.
70    ///
71    /// See [`Mem::replace`].
72    #[must_use]
73    fn mem_replace(&mut self, other: Self) -> Self where Self: Sized { Mem::replace(self, other) }
74
75    /// Replaces `self` with its default value, returning the previous value of `self`.
76    ///
77    /// See [`Mem::take`].
78    #[must_use]
79    fn mem_take(&mut self) -> Self where Self: Default, { Mem::take(self) }
80
81    /// Swaps the value of `self` and `other` without deinitializing either one.
82    ///
83    /// See [`Mem::swap`].
84    fn mem_swap(&mut self, other: &mut Self) where Self: Sized { Mem::swap(self, other); }
85
86    /// Returns the value of type `T` represented by the all-zero byte-pattern.
87    ///
88    /// # Safety
89    /// See [`Mem::zeroed`].
90    #[must_use]
91    #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "unsafe_layout")))]
92    #[cfg(all(not(feature = "safe_mem"), feature = "unsafe_layout"))]
93    unsafe fn mem_zeroed<T>() -> T { unsafe { Mem::zeroed::<T>() } }
94
95    /// Returns the value of type `T` represented by the all-zero byte-pattern.
96    ///
97    /// # Safety
98    /// See [`Mem::transmute_copy`].
99    #[must_use]
100    #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "unsafe_layout")))]
101    #[cfg(all(not(feature = "safe_mem"), feature = "unsafe_layout"))]
102    unsafe fn mem_transmute_copy<Src, Dst>(src: &Src) -> Dst {
103        unsafe { Mem::transmute_copy::<Src, Dst>(src) }
104    }
105
106    /// View a `Sync + Unpin` `self` as `&[u8]`.
107    ///
108    /// See [`Mem::as_bytes`], and for the `const` version for sized types
109    /// see [`Mem::as_bytes_sized`].
110    #[must_use]
111    #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "unsafe_slice")))]
112    #[cfg(all(not(feature = "safe_mem"), feature = "unsafe_slice"))]
113    fn mem_as_bytes(&self) -> &[u8] where Self: Sync + Unpin { Mem::as_bytes(self) }
114
115    /// View a `Sync + Unpin` `self` as `&mut [u8]`.
116    ///
117    /// See [`Mem::as_bytes_mut`].
118    #[must_use]
119    #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "unsafe_slice")))]
120    #[cfg(all(not(feature = "safe_mem"), feature = "unsafe_slice"))]
121    fn mem_as_bytes_mut(&mut self) -> &mut [u8] where Self: Sync + Unpin { Mem::as_bytes_mut(self) }
122}
devela/sys/mem/ext.rs

devela/sys/mem/
ext.rs
