write_only/
slice.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5//! Slices that only provide write-access, no read.
6
7mod non_volatile;
8mod volatile;
9
10pub use non_volatile::WriteOnlySlice;
11pub use volatile::VolatileWriteOnlySlice;
12
13/// A trait for objects which provide **dropping indexed** write access to their values.
14pub trait PutAt<T> {
15    /// Puts the value at `index` to the given value, dropping the old value.
16    ///
17    /// # Panics
18    ///
19    /// Panics if `index` is out of bounds.
20    fn put_at(&mut self, index: usize, value: T);
21
22    /// Puts the value at `index` to the given value, dropping the old value without checking bounds.
23    ///
24    /// For a safe alternative see [`PutAt::put_at`].
25    ///
26    /// # Safety
27    ///
28    /// Calling this method with an out-of-bounds index is undefined behavior.
29    unsafe fn put_at_unchecked(&mut self, index: usize, value: T);
30}
31
32/// A trait for objects which provide **dropping indexed** write access to their values from a slice.
33pub trait PutFromSliceAt<T>: PutAt<T> {
34    /// Clones the elements from `src` into self, starting at `offset`, dropping the old values.
35    ///
36    /// The length of `src` must be less than `self.len - offset`.
37    ///
38    /// # Panics
39    ///
40    /// This function will panic if the length of `src` is greater than `self.len - offset`.
41    fn put_cloning_from_slice_at(&mut self, src: &[T], offset: usize)
42    where
43        T: Clone;
44}
45
46/// A trait for objects which provide **non-dropping indexed** write access to their values.
47pub trait WriteAt<T> {
48    /// Performs a write of a memory location with the given value without reading or dropping the old value.
49    ///
50    /// # Panics
51    ///
52    /// Panics if `index` is out of bounds.
53    fn write_at(&mut self, index: usize, value: T);
54
55    /// Performs a write of a memory location with the given value without reading or dropping the old value.
56    ///
57    /// For a safe alternative see [`WriteAt::write_at`].
58    ///
59    /// # Safety
60    ///
61    /// Calling this method with an out-of-bounds index is undefined behavior.
62    unsafe fn write_at_unchecked(&mut self, index: usize, value: T);
63}
64
65/// A trait for objects which provide **non-dropping indexed** write access to their values from a slice.
66pub trait WriteFromSliceAt<T>: WriteAt<T> {
67    /// Copies the elements from `src` into `self`.
68    ///
69    /// The length of `src` must be less than `self.len - offset`.
70    ///
71    /// If `T` implements `Copy`, it can be more performant to use
72    /// [`WriteFromSliceAt::write_copying_from_slice_at`].
73    ///
74    /// # Panics
75    ///
76    /// This function will panic if the length of `src` is greater than `self.len - offset`.
77    fn write_cloning_from_slice_at(&mut self, src: &[T], offset: usize)
78    where
79        T: Clone;
80
81    /// Copies all elements from `src` into `self`, using a memcpy.
82    ///
83    /// The length of `src` must be less than `self.len - offset`.
84    ///
85    /// If `T` does not implement `Copy`, use [`WriteFromSliceAt::write_cloning_from_slice_at`].
86    ///
87    /// # Panics
88    ///
89    /// This function will panic if the length of `src` is greater than `self.len - offset`.
90    fn write_copying_from_slice_at(&mut self, src: &[T], offset: usize)
91    where
92        T: Copy;
93}
write_only/slice.rs

write_only/
slice.rs
