devela/data/dst/
buffer.rs

Help
1// devela::data::dst
2
3use crate::{Array, ConstDefault, Deref, DerefMut, MaybeUninit, MemPod};
4
5#[doc = crate::TAG_DATA_STRUCTURE!()]
6/// Represents the backing buffer for storing dynamically sized types.
7///
8/// # Safety
9/// Must conform to the following rules:
10/// - The `as_ref`/`as_mut` methods must return pointers to the same data.
11/// - The pointer returned by `as_mut` must be stable until either a call to
12///   `extend` or the value is moved (i.e. `let a = foo.as_mut().as_ptr();
13///   let b = foo.as_mut().as_ptr(); assert!(a == b)` always holds).
14/// - `extend` must not change any contained data
15///   (but may extend with unspecified values).
16pub unsafe trait DstBuf {
17    /// Inner type of the buffer
18    type Inner: MemPod;
19
20    /// Get the buffer slice as shared reference.
21    fn as_ref(&self) -> &[MaybeUninit<Self::Inner>];
22
23    /// Get the buffer slice as an exclusive reference.
24    fn as_mut(&mut self) -> &mut [MaybeUninit<Self::Inner>];
25
26    /// Extend the buffer (fallible).
27    fn extend(&mut self, len: usize) -> Result<(), ()>;
28
29    /// Convert a byte count to a word count (rounding up).
30    fn round_to_words(bytes: usize) -> usize {
31        super::round_to_words::<Self::Inner>(bytes)
32    }
33}
34
35// impl for an exclusive reference
36#[rustfmt::skip]
37unsafe impl<T, U> DstBuf for &mut T where U: MemPod, T: DstBuf<Inner = U> {
38    type Inner = T::Inner;
39
40    fn as_ref(&self) -> &[MaybeUninit<Self::Inner>] {
41        (**self).as_ref()
42    }
43    fn as_mut(&mut self) -> &mut [MaybeUninit<Self::Inner>] {
44        (**self).as_mut()
45    }
46    fn extend(&mut self, len: usize) -> Result<(), ()> {
47        (**self).extend(len)
48    }
49}
50
51// impl for array
52unsafe impl<T: MemPod, const CAP: usize> DstBuf for [MaybeUninit<T>; CAP] {
53    type Inner = T;
54
55    fn as_ref(&self) -> &[MaybeUninit<Self::Inner>] {
56        self
57    }
58    fn as_mut(&mut self) -> &mut [MaybeUninit<Self::Inner>] {
59        self
60    }
61    fn extend(&mut self, len: usize) -> Result<(), ()> {
62        if len > CAP {
63            Err(())
64        } else {
65            Ok(())
66        }
67    }
68}
69
70/// Vector backed structures, can be used to auto-grow the allocation
71///
72/// # Examples
73/// ```
74/// # use {devela::data::DstQueue, core::mem::MaybeUninit};
75/// let mut buf = DstQueue::<str, Vec<MaybeUninit<u8>>>::new();
76/// buf.push_back_str("Hello world!");
77/// buf.push_back_str("This is a very long string");
78/// buf.push_back_str("The buffer should keep growing as it needs to");
79/// for line in buf.iter() {
80///   println!("{}", line);
81/// }
82/// ```
83#[cfg(feature = "alloc")]
84#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
85unsafe impl<T: MemPod> DstBuf for crate::Vec<MaybeUninit<T>> {
86    type Inner = T;
87    fn as_ref(&self) -> &[MaybeUninit<Self::Inner>] {
88        self
89    }
90    fn as_mut(&mut self) -> &mut [MaybeUninit<Self::Inner>] {
91        self
92    }
93    fn extend(&mut self, len: usize) -> Result<(), ()> {
94        if len > self.len() {
95            self.resize(len, MaybeUninit::uninit());
96            let cap = self.capacity();
97            self.resize(cap, MaybeUninit::uninit());
98        }
99        Ok(())
100    }
101}
102
103#[doc = crate::TAG_DATA_STRUCTURE!()]
104/// A static array for storing <abbr title="Dynamically sized type">DST</abbr>s.
105pub struct DstArray<T, const CAP: usize> {
106    inner: Array<MaybeUninit<T>, CAP>,
107}
108impl<T, const CAP: usize> Deref for DstArray<T, CAP> {
109    type Target = Array<MaybeUninit<T>, CAP>;
110
111    fn deref(&self) -> &Self::Target {
112        &self.inner
113    }
114}
115impl<T, const CAP: usize> DerefMut for DstArray<T, CAP> {
116    fn deref_mut(&mut self) -> &mut Self::Target {
117        &mut self.inner
118    }
119}
120impl<T: MemPod, const CAP: usize> Default for DstArray<T, CAP> {
121    fn default() -> Self {
122        Self { inner: Array::new([MaybeUninit::uninit(); CAP]) }
123    }
124}
125impl<T: MemPod, const CAP: usize> ConstDefault for DstArray<T, CAP> {
126    const DEFAULT: Self = Self {
127        inner: Array::new_bare([MaybeUninit::uninit(); CAP]),
128    };
129}
130#[rustfmt::skip]
131unsafe impl<T: MemPod, const CAP: usize> DstBuf for DstArray<T, CAP> {
132    type Inner = T;
133    fn as_ref(&self) -> &[MaybeUninit<Self::Inner>] {
134        &self.inner
135    }
136    fn as_mut(&mut self) -> &mut [MaybeUninit<Self::Inner>] {
137        &mut self.inner
138    }
139    fn extend(&mut self, len: usize) -> Result<(), ()> {
140        if len > CAP { Err(()) } else { Ok(()) }
141    }
142}
143
144/// A statically allocated buffer for storing <abbr title="Dynamically sized
145/// type">DST</abbr>s with pointer alignment.
146pub type DstArrayUsize<const CAP: usize> = DstArray<usize, CAP>;
147
148/// A dynamically allocated buffer for storing <abbr title="Dynamically sized
149/// type">DST</abbr>s with pointer alignment.
150#[cfg(feature = "alloc")]
151#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
152pub type DstVecUsize = crate::Vec<MaybeUninit<usize>>;
153
154// MAYBE
155// /// A DST buffer backing onto a Vec.
156// #[cfg(feature = "alloc")]
157// #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
158// pub struct DstVec<T: MemPod>(crate::Vec<MaybeUninit<T>>);
159// impl<T: MemPod> Deref for DstVec<T> {
160//     type Target = Vec<MaybeUninit<T>>;
161//
162//     fn deref(&self) -> &Self::Target {
163//         &self.0
164//     }
165// }
166// impl<T: MemPod> DerefMut for DstVec<T> {
167//     fn deref_mut(&mut self) -> &mut Self::Target {
168//         &mut self.0
169//     }
170// }
devela/data/dst/buffer.rs

devela/data/dst/
buffer.rs
