devela/data/layout/buffer/linear/_example.rs
1// devela/src/data/layout/buffer/linear/_example.rs
2//
3// TOC
4// - BufferLinearStaticExample
5// - BufferLinearViewExample
6// - BufferLinearAllocExample
7//
8// NOTES
9// - doclinks use #method notation to ensure they wont link to /all version.
10
11use crate::buffer_linear;
12
13buffer_linear!(
14 #[doc = crate::_tags!(example data_structure)]
15 /// A static linear buffer over contiguous storage, made with [`buffer_linear!`].
16 #[doc = crate::_doc_meta!{
17 location("data/layout/buffer", struct BufferLinearStaticExample),
18 test_size_of(BufferLinearStaticExample<(), [(); 8]> = 1|8; niche Option),
19 test_size_of(BufferLinearStaticExample<u8, [u8; 8]> = 9|72; niche Option),
20 test_size_of(BufferLinearStaticExample<i32, [i32; 8]> = 36|288; niche Option),
21 #[cfg(target_pointer_width = "32")]
22 test_size_of(BufferLinearStaticExample<char, &[i32]> = 12|96; niche Option),
23 #[cfg(target_pointer_width = "64")]
24 test_size_of(BufferLinearStaticExample<char, &[i32]> = 24|192; niche Option),
25 }]
26 ///
27 /// # Methods
28 ///
29 /// - [common methods](#impl-BufferLinearStaticExample<T,+S>)
30 // %common_tracked:
31 /// - Size:
32 /// [len](#method.len) *([_prim](#method.len_prim))*,
33 /// [is_empty](#method.is_empty).
34 //
35 /// - [Fully initialized array](#impl-BufferLinearStaticExample<T,+[T;+CAP]>)
36 /// (`array`)
37 /// - Constructors:
38 /// [new](#method.new) *([_init](#method.new_init))*,
39 /// from_array *([from_array_clamped](#method.from_array_clamped),
40 /// [_prim](#method.from_array_clamped_prim))*,
41 /// from_slice (*[_clone](#method.from_slice_clone),
42 /// [_copy](#method.from_slice_copy),
43 /// [_move_default](#method.from_slice_move_default))*.
44 // %common_static:
45 /// - Capacity:
46 /// [CAP](#associatedconstant.CAP) *([_PRIM](#associatedconstant.CAP_PRIM))*,
47 /// [capacity](#method.capacity) *([_prim](#method.capacity_prim))*,
48 /// [remaining_capacity](#method.remaining_capacity)
49 /// *([_prim](#method.remaining_capacity_prim))*,
50 /// [is_full](#method.is_full).
51 //
52 /// - Logical range control:
53 /// [clear](#method.clear) *([_copy](#method.clear_copy))*,
54 /// [truncate](#method.truncate), *([_copy](#method.truncate_copy),
55 /// [_prim](#method.truncate_prim), [_prim_copy](#method.truncate_prim_copy))*.
56 /// - Push:
57 /// [push_back](#method.push_back) *([_copy](#method.push_back_copy))*,
58 /// [push_slice](#method.push_slice)
59 /// *([_copy](#method.push_slice_copy), [_copy_exact](#method.push_slice_copy_exact))*.
60 /// - Pop:
61 /// [pop_back_clone](#method.pop_back_clone),
62 /// [pop_back_copy](#method.pop_back_copy).
63 /// - Peek:
64 /// [peek_back](#method.peek_back) *([_mut](#method.peek_mut_back))*.
65 /// - Get:
66 /// [get](#method.get) *([_mut](#method.get_mut))*.
67 /// - Take:
68 /// [take_default](#method.take_default),
69 /// [take_init](#method.take_init),
70 /// [take_with](#method.take_with) *([_copy](#method.take_with_copy))*.
71 /// - Views:
72 /// [as_slice](#method.as_slice) *([_mut](#method.as_mut_slice))*,
73 // %common_iter_visit:
74 /// - Iteration:
75 /// [iter](#method.iter) *([_mut](#method.iter_mut))*.
76 /// - Visitation:
77 /// [visit_each](#method.visit_each) *([_mut](#method.visit_each_mut))*,
78 /// [visit_slice](#method.visit_slice) *([_mut](#method.visit_mut_slice))*.
79 //
80 // --------------------------------------------------------------------------
81 /// - [Partially initialized array](#impl-BufferLinearStaticExample<T,+[MaybeUninit<T>;+CAP]>)
82 /// (`uninit`)<sup title="unsafe implementation">⚠</sup>
83 /// - Constructors:
84 /// [new](#method.new-1),
85 /// from_array *([_exact](#method.from_array_exact)
86 /// [_unchecked](#method.from_array_unchecked)<sup title="unsafe method">⚠</sup>)*,
87 /// from_slice (*[_clone](#method.from_slice_clone-1),
88 /// [_copy](#method.from_slice_copy-1),
89 /// [_move_default](#method.from_slice_move_default-1),
90 /// [_move_init](#method.from_slice_move_init-1))*.
91 // %common_static:
92 /// - Capacity:
93 /// [CAP](#associatedconstant.CAP-1) *([_PRIM](#associatedconstant.CAP_PRIM-1))*,
94 /// [capacity](#method.capacity-1) *([_prim](#method.capacity_prim-1))*,
95 /// [remaining_capacity](#method.remaining_capacity-1)
96 /// *([_prim](#method.remaining_capacity_prim-1))*,
97 /// [is_full](#method.is_full-1).
98 //
99 /// - Logical range control:
100 /// [clear](#method.clear-1),
101 /// [drop_back](#method.drop_back),
102 /// [truncate](#method.truncate-1), *([_prim](#method.truncate_prim-1))*.
103 /// - Push:
104 /// [push_back](#method.push_back-1),
105 /// [push_slice](#method.push_slice) *([_copy](#method.push_slice_copy),
106 /// [_copy_exact](#method.push_slice_copy_exact))*.
107 /// - Pop:
108 /// [pop_back](#method.pop_back).
109 /// - Peek:
110 /// [peek_back](#method.peek_back-1) *([_mut](#method.peek_mut_back-1))*.
111 /// - Get:
112 /// [get](#method.get-1) *([_mut](#method.get_mut-1))*.
113 /// - Views:
114 /// [as_slice](#method.as_slice-2) *([_mut](#method.as_mut_slice-2))*,
115 // %common_iter_visit:
116 /// - Iteration:
117 /// [iter](#method.iter-2) *([_mut](#method.iter_mut-2))*.
118 /// - Visitation:
119 /// [visit_each](#method.visit_each-2) *([_mut](#method.visit_each_mut-2))*,
120 /// [visit_slice](#method.visit_slice-2) *([_mut](#method.visit_mut_slice-2))*.
121 //
122 // --------------------------------------------------------------------------
123 /// - [Fully initialized array of options](#impl-BufferLinearStaticExample<T,+[Option<T>;+CAP]>)
124 /// (`option`)
125 /// - Constructors:
126 /// [new](#method.new-2),
127 /// from_array (*[_clone](#method.from_array_clone), [_copy](#method.from_array_copy),
128 /// [_unchecked](#method.from_array_unchecked-1)<sup title="unsafe method">⚠</sup>,
129 /// [_linear](#method.from_array_linear),
130 /// [_prefix](#method.from_array_prefix))*,
131 /// from_slice *([_clone](#method.from_slice_clone-2),
132 /// [_copy](#method.from_slice_copy-2),
133 /// [_move_default](#method.from_slice_move_default-2),
134 /// [_move_init](#method.from_slice_move_init-2))*.
135 // %common_static:
136 /// - Capacity:
137 /// [CAP](#associatedconstant.CAP-2) *([_PRIM](#associatedconstant.CAP_PRIM-2))*,
138 /// [capacity](#method.capacity-2) *([_prim](#method.capacity_prim-2))*,
139 /// [remaining_capacity](#method.remaining_capacity-2)
140 /// *([_prim](#method.remaining_capacity_prim-2))*,
141 /// [is_full](#method.is_full-2).
142 //
143 /// - Logical range control:
144 /// [clear](#method.clear-2),
145 /// [truncate](#method.truncate-2).
146 /// - Push:
147 /// [push_back](#method.push_back-2) *([_copy](#method.push_back_copy-1))*,
148 /// [push_slice](#method.push_slice)
149 /// *([_copy](#method.push_slice_copy), [_copy_exact](#method.push_slice_copy_exact))*.
150 /// - Pop:
151 /// [pop_back](#method.pop_back-1).
152 /// - Peek:
153 /// [peek_back](#method.peek_back-2) *([_mut](#method.peek_mut_back-2))*.
154 /// - Get:
155 /// [get](#method.get-2) *([_mut](#method.get_mut-2))*.
156 /// - Swap:
157 /// [swap_remove](#method.swap_remove) *([_prim](#method.swap_remove_prim),
158 /// [_copy](#method.swap_remove_copy), [_copy_prim](#method.swap_remove_copy_prim))*.
159 /// - Views:
160 /// [as_slice](#method.as_slice) *([_mut](#method.as_mut_slice))*,
161 /// - Iteration:
162 /// [iter](#method.iter) *([_mut](#method.iter_mut))*.
163 /// - Visitation:
164 /// [visit_each](#method.visit_each) *([_mut](#method.visit_each_mut))*,
165 /// [visit_slice](#method.visit_slice) *([_mut](#method.visit_mut_slice))*.
166 pub struct BufferLinearStaticExample: static (crate::NonValueU8<{u8::MAX}>);
167 array,
168 #[cfg(all(not(feature = "safe_data"), feature = "unsafe_array"))]
169 #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_array")))]
170 uninit,
171 option,
172);
173
174buffer_linear!(
175 #[doc = crate::_tags!(example data_structure)]
176 /// A linear buffer view over contiguous storage, made with [`buffer_linear!`].
177 #[doc = crate::_doc_meta!{
178 location("data/layout/buffer", struct BufferLinearViewExample),
179 }]
180 ///
181 /// # Methods
182 ///
183 /// - [common methods](#impl-BufferLinearViewExample<'a,+T,+S>)
184 // %common_tracked:
185 /// - Size:
186 /// [len](#method.len) *([_prim](#method.len_prim))*,
187 /// [is_empty](#method.is_empty).
188 ///
189 /// - [Exclusive slice](#impl-BufferLinearViewExample<'a,+T,+%26mut+[T]>) (slice_mut)
190 /// - Constructors:
191 /// [try_new](#method.try_new),
192 /// [new_truncated](#method.new_truncated)
193 /// [try_from_slice](#method.try_from_slice),
194 /// [from_slice_with](#method.from_slice_with),
195 /// [from_slice_truncated](#method.from_slice_truncated).
196 // %common_view:
197 /// - Capacity:
198 /// [capacity](#method.capacity) *([_prim](#method.capacity_prim))*,
199 /// [remaining_capacity](#method.remaining_capacity)
200 /// *([_prim](#method.remaining_capacity_prim))*,
201 /// [is_full](#method.is_full).
202 //
203 /// - Logical range control:
204 /// [clear](#method.clear),
205 /// [truncate](#method.truncate), *([_prim](#method.truncate_prim))*.
206 /// - Push:
207 /// [push_back](#method.push_back) *([_copy](#method.push_back_copy))*,
208 /// [push_slice](#method.push_slice)
209 /// *([_copy](#method.push_slice_copy), [_copy_exact](#method.push_slice_copy_exact))*.
210 /// - Pop:
211 /// [pop_back_clone](#method.pop_back_clone),
212 /// [pop_back_copy](#method.pop_back_copy).
213 /// - Peek:
214 /// [peek_back](#method.peek_back) *([_mut](#method.peek_mut_back))*.
215 /// - Get:
216 /// [get](#method.get) *([_mut](#method.get_mut))*.
217 /// - Views:
218 /// [as_slice](#method.as_slice) *([_mut](#method.as_mut_slice))*,
219 // %common_iter_visit:
220 /// - Iteration:
221 /// [iter](#method.iter) *([_mut](#method.iter_mut))*.
222 /// - Visitation:
223 /// [visit_each](#method.visit_each) *([_mut](#method.visit_each_mut))*,
224 /// [visit_slice](#method.visit_slice) *([_mut](#method.visit_mut_slice))*.
225 //
226 // --------------------------------------------------------------------------
227 /// - [Shared slice](#impl-BufferLinearViewExample<'a,+T,+%26[T]>)
228 /// (`slice`)
229 /// - Constructors:
230 /// [try_from_slice](#method.try_from_slice-1),
231 /// [from_slice_with](#method.from_slice_with-1),
232 /// [from_slice_truncated](#method.from_slice_truncated-1).
233 // %common_view:
234 /// - Capacity:
235 /// [capacity](#method.capacity-1) *([_prim](#method.capacity_prim-1))*,
236 /// [remaining_capacity](#method.remaining_capacity-1)
237 /// *([_prim](#method.remaining_capacity_prim-1))*,
238 /// [is_full](#method.is_full-1).
239 //
240 /// - Peek:
241 /// [peek_back](#method.peek_back-1).
242 /// - Get:
243 /// [get](#method.get-1).
244 /// - Views:
245 /// [as_slice](#method.as_slice-1).
246 // %common_iter_visit:
247 /// - Iteration:
248 /// [iter](#method.iter-1).
249 /// - Visitation:
250 /// [visit_each](#method.visit_each-1),
251 /// [visit_slice](#method.visit_slice-1).
252 pub struct BufferLinearViewExample: view (crate::NonValueU8<{u8::MAX}>);
253 slice_mut,
254 slice,
255);
256
257#[cfg(feature = "alloc")]
258buffer_linear!(
259 #[doc = crate::_tags!(example data_structure)]
260 /// An owned linear buffer over a [`Vec`], made with [`buffer_linear!`].
261 #[doc = crate::_doc_meta!{
262 location("data/layout/buffer", struct BufferLinearAllocExample),
263 #[cfg(target_pointer_width = "32")]
264 test_size_of(BufferLinearAllocExample<char, &[i32]> = 8|64; niche Option),
265 #[cfg(target_pointer_width = "64")]
266 test_size_of(BufferLinearAllocExample<char, &[i32]> = 16|128; niche Option),
267 }]
268 /// # Methods
269 ///
270 /// - [Dynamically sized array](#impl-BufferLinearAllocExample<T,+Vec<T>>)
271 /// (`vec`)
272 /// - Constructors:
273 /// [new](#method.new) *([_init](#method.new_init))*,
274 /// [with_capacity](#method.with_capacity) *([_prim](#method.with_capacity_prim))*.
275 /// - Size:
276 /// [len](#method.len) *([_prim](#method.len_prim))*,
277 /// [is_empty](#method.is_empty),
278 /// - Capacity:
279 /// [capacity](#method.capacity) *([_prim](#method.capacity_prim))*,
280 /// [remaining_capacity](#method.remaining_capacity)
281 /// *([_prim](#method.remaining_capacity_prim))*,
282 /// [is_full](#method.is_full).
283 /// - Logical range control:
284 /// [clear](#method.clear),
285 /// [truncate](#method.truncate), *([_prim](#method.truncate_prim))*.
286 /// - Push:
287 /// [push_back](#method.push_back),
288 /// [push_slice](#method.push_slice).
289 /// - Pop:
290 /// [pop_back](#method.pop_back).
291 /// - Peek:
292 /// [peek_back](#method.peek_back) *([_mut](#method.peek_mut_back))*.
293 /// - Get:
294 /// [get](#method.get) *([_mut](#method.get_mut))*.
295 /// - Take:
296 /// [take_default](#method.take_default),
297 /// [take_init](#method.take_init),
298 /// [take_with](#method.take_with), *([_copy](#method.take_with_copy))*.
299 /// - Views:
300 /// [as_slice](#method.as_slice) *([_mut](#method.as_mut_slice))*,
301 // %common_iter_visit:
302 /// - Iteration:
303 /// [iter](#method.iter) *([_mut](#method.iter_mut))*.
304 /// - Visitation:
305 /// [visit_each](#method.visit_each) *([_mut](#method.visit_each_mut))*,
306 /// [visit_slice](#method.visit_slice) *([_mut](#method.visit_mut_slice))*.
307 #[cfg_attr(nightly_doc, doc(cfg(feature = "alloc")))]
308 pub struct BufferLinearAllocExample: alloc (crate::NonValueU8<{u8::MAX}>);
309 vec,
310);
311
312#[cfg(test)]
313mod tests {
314 use super::*;
315
316 #[test]
317 fn array() {
318 let mut buf = BufferLinearStaticExample::<i32, [i32; 8]>::new_init();
319 buf.push_back(10).unwrap();
320 buf.push_back(20).unwrap();
321 assert_eq!(buf.as_slice(), &[10, 20]);
322 }
323 #[test]
324 fn option() {
325 let mut buf = BufferLinearStaticExample::<i32, [Option<i32>; 8]>::new();
326 buf.push_back(10).unwrap();
327 buf.push_back(20).unwrap();
328 assert_eq!(buf.as_slice(), &[Some(10), Some(20)]);
329 }
330 #[test]
331 #[cfg(all(not(feature = "safe_data"), feature = "unsafe_array"))]
332 fn uninit() {
333 let mut buf = BufferLinearStaticExample::<i32, [crate::MaybeUninit<i32>; 8]>::new();
334 buf.push_back(10).unwrap();
335 buf.push_back(20).unwrap();
336 assert_eq!(buf.as_slice(), &[10, 20]);
337 }
338}