diff --git a/.rustfmt.toml b/.rustfmt.toml new file mode 100644 index 0000000000..9cfcdf7f2d --- /dev/null +++ b/.rustfmt.toml @@ -0,0 +1,3 @@ +imports_granularity = "Crate" +comment_width = 100 +wrap_comments = true diff --git a/README.md b/README.md index 6d84916b25..03ab4e5601 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,15 @@ $ # run only for example histbuf tests $ cargo test histbuf --features serde ``` +# Formatting + +Like most Rust projects, we use `rustfmt` to keep the formatting of code consistent. However, we +make use of cecertain options that are currently only available in the nightly version: + +```console +$ cargo +nightly fmt --all +``` + ## License Licensed under either of diff --git a/src/c_string.rs b/src/c_string.rs index cf4ce3013c..9ec011cf1c 100644 --- a/src/c_string.rs +++ b/src/c_string.rs @@ -106,11 +106,12 @@ impl CString { /// /// # Safety /// - /// - The memory pointed to by `ptr` must contain a valid nul terminator at the - /// end of the string. - /// - `ptr` must be valid for reads of bytes up to and including the nul terminator. - /// This means in particular: - /// - The entire memory range of this `CStr` must be contained within a single allocated object! + /// - The memory pointed to by `ptr` must contain a valid nul terminator at the end of the + /// string. + /// - `ptr` must be valid for reads of bytes up to and including the nul terminator. This means + /// in particular: + /// - The entire memory range of this `CStr` must be contained within a single allocated + /// object! /// - `ptr` must be non-nul even for a zero-length `CStr`. /// /// # Example @@ -190,7 +191,8 @@ impl CString { match CStr::from_bytes_with_nul(bytes) { Ok(_) => { - // SAFETY: A string is left in a valid state because appended bytes are nul-terminated. + // SAFETY: A string is left in a valid state because appended bytes are + // nul-terminated. unsafe { self.extend_from_bytes_unchecked(bytes) }?; Ok(()) diff --git a/src/deque.rs b/src/deque.rs index ef35c0254f..340f3ae182 100644 --- a/src/deque.rs +++ b/src/deque.rs @@ -33,14 +33,18 @@ //! } //! ``` -use crate::vec::{OwnedVecStorage, VecStorage, VecStorageInner, ViewVecStorage}; -use crate::CapacityError; -use core::cmp::Ordering; -use core::fmt; -use core::iter::FusedIterator; -use core::marker::PhantomData; -use core::mem::{ManuallyDrop, MaybeUninit}; -use core::{ptr, slice}; +use crate::{ + vec::{OwnedVecStorage, VecStorage, VecStorageInner, ViewVecStorage}, + CapacityError, +}; +use core::{ + cmp::Ordering, + fmt, + iter::FusedIterator, + marker::PhantomData, + mem::{ManuallyDrop, MaybeUninit}, + ptr, slice, +}; #[cfg(feature = "zeroize")] use zeroize::Zeroize; @@ -173,14 +177,16 @@ impl Deque { /// Returns the maximum number of elements the deque can hold. /// - /// This method is not available on a `DequeView`, use [`storage_capacity`](DequeInner::storage_capacity) instead. + /// This method is not available on a `DequeView`, use + /// [`storage_capacity`](DequeInner::storage_capacity) instead. pub const fn capacity(&self) -> usize { N } /// Returns the number of elements currently in the deque. /// - /// This method is not available on a `DequeView`, use [`storage_len`](DequeInner::storage_len) instead. + /// This method is not available on a `DequeView`, use [`storage_len`](DequeInner::storage_len) + /// instead. pub const fn len(&self) -> usize { if self.full { N @@ -452,8 +458,8 @@ impl + ?Sized> DequeInner { self.storage_capacity() - free, ); - // because the deque wasn't contiguous, we know that `tail_len < self.len == slice.len()`, - // so this will never panic. + // because the deque wasn't contiguous, we know that `tail_len < self.len == + // slice.len()`, so this will never panic. slice.rotate_left(back_len); // the used part of the buffer now is `free..self.capacity()`, so set @@ -465,7 +471,8 @@ impl + ?Sized> DequeInner { // head is shorter so: // 1. copy head backwards // 2. rotate used part of the buffer - // 3. update head to point to the new beginning (which is the beginning of the buffer) + // 3. update head to point to the new beginning (which is the beginning of the + // buffer) unsafe { // if there is no free space in the buffer, then the slices are already @@ -483,8 +490,8 @@ impl + ?Sized> DequeInner { // next to each other, all the elements in the range are initialized. let slice: &mut [T] = slice::from_raw_parts_mut(buffer_ptr, len); - // because the deque wasn't contiguous, we know that `head_len < self.len == slice.len()` - // so this will never panic. + // because the deque wasn't contiguous, we know that `head_len < self.len == + // slice.len()` so this will never panic. slice.rotate_right(front_len); // the used part of the buffer now is `0..self.len`, so set @@ -844,11 +851,11 @@ impl + ?Sized> DequeInner { } // Safety: - // * Any slice passed to `drop_in_place` is valid; the second case has - // `len <= front.len()` and returning on `len > self.storage_len()` ensures - // `begin <= back.len()` in the first case - // * Deque front/back cursors are moved before calling `drop_in_place`, - // so no value is dropped twice if `drop_in_place` panics + // * Any slice passed to `drop_in_place` is valid; the second case has `len <= front.len()` + // and returning on `len > self.storage_len()` ensures `begin <= back.len()` in the first + // case + // * Deque front/back cursors are moved before calling `drop_in_place`, so no value is + // dropped twice if `drop_in_place` panics unsafe { // If new desired length is greater or equal, we don't need to act. if len >= self.storage_len() { @@ -865,8 +872,9 @@ impl + ?Sized> DequeInner { let drop_back = back.get_unchecked_mut(begin..) as *mut _; // Self::to_physical_index returns the index `len` units _after_ the front cursor, - // meaning we can use it to find the decremented index for `back` for non-contiguous deques, - // as well as determine where the new "cap" for front needs to be placed for contiguous deques. + // meaning we can use it to find the decremented index for `back` for non-contiguous + // deques, as well as determine where the new "cap" for front needs + // to be placed for contiguous deques. self.back = self.to_physical_index(len); self.full = false; @@ -880,8 +888,9 @@ impl + ?Sized> DequeInner { self.back = self.to_physical_index(len); self.full = false; - // If `drop_front` causes a panic, the Dropper will still be called to drop it's slice during unwinding. - // In either case, front will always be dropped before back. + // If `drop_front` causes a panic, the Dropper will still be called to drop it's + // slice during unwinding. In either case, front will always be + // dropped before back. let _back_dropper = Dropper(&mut *drop_back); ptr::drop_in_place(drop_front); } @@ -970,7 +979,8 @@ impl + ?Sized> DequeInner { cur += 1; idx += 1; } - // Stage 2: Swap retained values into current idx, building a contiguous chunk from 0 to idx. + // Stage 2: Swap retained values into current idx, building a contiguous chunk from 0 to + // idx. while cur < len { let val = self .get_mut(cur) diff --git a/src/history_buf.rs b/src/history_buf.rs index 67df4cd7ee..8a15146f7d 100644 --- a/src/history_buf.rs +++ b/src/history_buf.rs @@ -31,12 +31,7 @@ //! assert_eq!(avg, 4); //! ``` -use core::fmt; -use core::marker::PhantomData; -use core::mem::MaybeUninit; -use core::ops::Deref; -use core::ptr; -use core::slice; +use core::{fmt, marker::PhantomData, mem::MaybeUninit, ops::Deref, ptr, slice}; #[cfg(feature = "zeroize")] use zeroize::Zeroize; @@ -51,18 +46,23 @@ mod storage { /// /// There's two implementations available: /// - /// - [`OwnedHistoryBufStorage`]: stores the data in an array `[T; N]` whose size is known at compile time. + /// - [`OwnedHistoryBufStorage`]: stores the data in an array `[T; N]` whose size is known at + /// compile time. /// - [`ViewHistoryBufStorage`]: stores the data in an unsized `[T]`. /// - /// This allows [`HistoryBuf`] to be generic over either sized or unsized storage. The [`histbuf`] - /// module contains a [`HistoryBufInner`] struct that's generic on [`HistoryBufStorage`], - /// and two type aliases for convenience: + /// This allows [`HistoryBuf`] to be generic over either sized or unsized storage. The + /// [`histbuf`] module contains a [`HistoryBufInner`] struct that's generic on + /// [`HistoryBufStorage`], and two type aliases for convenience: /// - /// - [`HistoryBuf`](super::HistoryBuf) = `HistoryBufInner>` - /// - [`HistoryBufView`](super::HistoryBufView) = `HistoryBufInner>` + /// - [`HistoryBuf`](super::HistoryBuf) = `HistoryBufInner>` + /// - [`HistoryBufView`](super::HistoryBufView) = `HistoryBufInner>` /// - /// `HistoryBuf` can be unsized into `HistoryBufView`, either by unsizing coercions such as `&mut HistoryBuf -> &mut HistoryBufView` or - /// `Box -> Box`, or explicitly with [`.as_view()`](super::HistoryBuf::as_view) or [`.as_mut_view()`](super::HistoryBuf::as_mut_view). + /// `HistoryBuf` can be unsized into `HistoryBufView`, either by unsizing coercions such as + /// `&mut HistoryBuf -> &mut HistoryBufView` or `Box -> Box`, or + /// explicitly with [`.as_view()`](super::HistoryBuf::as_view) or + /// [`.as_mut_view()`](super::HistoryBuf::as_mut_view). /// /// This trait is sealed, so you cannot implement it for your own types. You can only use /// the implementations provided by this crate. @@ -75,7 +75,8 @@ mod storage { pub trait HistoryBufStorage: HistoryBufSealedStorage {} pub trait HistoryBufSealedStorage { - // part of the sealed trait so that no trait is publicly implemented by `OwnedHistoryBufStorage` besides `Storage` + // part of the sealed trait so that no trait is publicly implemented by + // `OwnedHistoryBufStorage` besides `Storage` fn borrow(&self) -> &[MaybeUninit]; fn borrow_mut(&mut self) -> &mut [MaybeUninit]; fn as_hist_buf_view(this: &HistoryBufInner) -> &HistoryBufView @@ -92,7 +93,8 @@ mod storage { pub(crate) buffer: T, } - /// Implementation of [`HistoryBufStorage`] that stores the data in an array `[T; N]` whose size is known at compile time. + /// Implementation of [`HistoryBufStorage`] that stores the data in an array `[T; N]` whose size + /// is known at compile time. pub type OwnedHistoryBufStorage = HistoryBufStorageInner<[MaybeUninit; N]>; /// Implementation of [`HistoryBufStorage`] that stores the data in an unsized `[T]`. @@ -651,8 +653,10 @@ impl DoubleEndedIterator for OldestOrdered<'_, T> { #[cfg(test)] mod tests { - use core::fmt::Debug; - use core::sync::atomic::{AtomicUsize, Ordering}; + use core::{ + fmt::Debug, + sync::atomic::{AtomicUsize, Ordering}, + }; use static_assertions::assert_not_impl_any; diff --git a/src/index_map.rs b/src/index_map.rs index 0fd14cc3c5..d61b0b40fc 100644 --- a/src/index_map.rs +++ b/src/index_map.rs @@ -665,8 +665,8 @@ where match self.core.insert(self.hash_val, self.key, value) { Insert::Success(inserted) => { unsafe { - // SAFETY: Already checked existence at instantiation and the only mutable reference - // to the map is internally held. + // SAFETY: Already checked existence at instantiation and the only mutable + // reference to the map is internally held. Ok(&mut (*self.core.entries.as_mut_ptr().add(inserted.index)).value) } } @@ -1592,8 +1592,8 @@ impl<'a, K, V> Iterator for Values<'a, K, V> { /// A mutable iterator over the values of a [`IndexMap`]. /// -/// This `struct` is created by the [`values_mut`](IndexMap::values_mut) method on [`IndexMap`]. See its -/// documentation for more. +/// This `struct` is created by the [`values_mut`](IndexMap::values_mut) method on [`IndexMap`]. See +/// its documentation for more. pub struct ValuesMut<'a, K, V> { iter: slice::IterMut<'a, Bucket>, } diff --git a/src/linear_map.rs b/src/linear_map.rs index fcbe37b876..c62fcc8b62 100644 --- a/src/linear_map.rs +++ b/src/linear_map.rs @@ -21,15 +21,17 @@ mod storage { /// - [`OwnedStorage`]: stores the data in an array whose size is known at compile time. /// - [`ViewStorage`]: stores the data in an unsized slice /// - /// This allows [`LinearMap`] to be generic over either sized or unsized storage. The [`linear_map`](super) - /// module contains a [`LinearMapInner`] struct that's generic on [`LinearMapStorage`], - /// and two type aliases for convenience: + /// This allows [`LinearMap`] to be generic over either sized or unsized storage. The + /// [`linear_map`](super) module contains a [`LinearMapInner`] struct that's generic on + /// [`LinearMapStorage`], and two type aliases for convenience: /// /// - [`LinearMap`](crate::linear_map::LinearMap) = `LinearMapInner>` /// - [`LinearMapView`](crate::linear_map::LinearMapView) = `LinearMapInner>` /// - /// `LinearMap` can be unsized into `StrinsgView`, either by unsizing coercions such as `&mut LinearMap -> &mut LinearMapView` or - /// `Box -> Box`, or explicitly with [`.as_view()`](crate::linear_map::LinearMap::as_view) or [`.as_mut_view()`](crate::linear_map::LinearMap::as_mut_view). + /// `LinearMap` can be unsized into `StrinsgView`, either by unsizing coercions such as `&mut + /// LinearMap -> &mut LinearMapView` or `Box -> Box`, or + /// explicitly with [`.as_view()`](crate::linear_map::LinearMap::as_view) or + /// [`.as_mut_view()`](crate::linear_map::LinearMap::as_mut_view). /// /// This trait is sealed, so you cannot implement it for your own types. You can only use /// the implementations provided by this crate. @@ -85,7 +87,8 @@ mod storage { } pub use storage::LinearMapStorage; -/// Implementation of [`LinearMapStorage`] that stores the data in an array whose size is known at compile time. +/// Implementation of [`LinearMapStorage`] that stores the data in an array whose size is known at +/// compile time. pub type OwnedStorage = OwnedVecStorage<(K, V), N>; /// Implementation of [`LinearMapStorage`] that stores the data in an unsized slice. pub type ViewStorage = ViewVecStorage<(K, V)>; @@ -590,7 +593,8 @@ where /// An iterator that moves out of a [`LinearMap`]. /// -/// This struct is created by calling the [`into_iter`](LinearMap::into_iter) method on [`LinearMap`]. +/// This struct is created by calling the [`into_iter`](LinearMap::into_iter) method on +/// [`LinearMap`]. pub struct IntoIter where K: Eq, diff --git a/src/mpmc.rs b/src/mpmc.rs index ec36c84be2..e64c0a94a6 100644 --- a/src/mpmc.rs +++ b/src/mpmc.rs @@ -69,7 +69,8 @@ //! //! # Benchmark //! -//! Measured on an ARM Cortex-M3 core running at 8 MHz and with zero flash wait cycles, compiled with `-C opt-level=z`: +//! Measured on an ARM Cortex-M3 core running at 8 MHz and with zero flash wait cycles, compiled +//! with `-C opt-level=z`: //! //! | Method | Time | N | //! |:----------------------------|-----:|---:| @@ -80,15 +81,14 @@ //! | `Queue::::dequeue()` | 53 | 1 | //! | `Queue::::dequeue()` | 71 | 2 | //! -//! - N denotes the number of interruptions. On Cortex-M, an interruption consists of an -//! interrupt handler preempting the would-be atomic section of the `enqueue`/`dequeue` -//! operation. Note that it does *not* matter if the higher priority handler uses the queue or -//! not. +//! - N denotes the number of interruptions. On Cortex-M, an interruption consists of an interrupt +//! handler preempting the would-be atomic section of the `enqueue`/`dequeue` operation. Note that +//! it does *not* matter if the higher priority handler uses the queue or not. //! - All execution times are in clock cycles (1 clock cycle = 125 ns). //! - Execution time is *dependent* on `mem::size_of::()`, as both operations include //! `ptr::read::()` or `ptr::write::()` in their successful path. -//! - The numbers reported correspond to the successful path, i.e. `dequeue` returning `Some` -//! and `enqueue` returning `Ok`. +//! - The numbers reported correspond to the successful path, i.e. `dequeue` returning `Some` and +//! `enqueue` returning `Ok`. //! //! # References //! @@ -146,7 +146,8 @@ pub type Queue = QueueInner>; /// A [`Queue`] with dynamic capacity. /// -/// [`Queue`] coerces to `QueueView`. `QueueView` is `!Sized`, meaning it can only ever be used by reference. +/// [`Queue`] coerces to `QueueView`. `QueueView` is `!Sized`, meaning it can only ever be used by +/// reference. pub type QueueView = QueueInner; impl Queue { @@ -158,8 +159,8 @@ impl Queue { /// # Deprecation /// ///
- /// The current implementation of `mpmc` is marked as deprecated due to not being truly lock-free - ///
+ /// The current implementation of `mpmc` is marked as deprecated due to not being truly + /// lock-free /// /// If a thread is parked, or pre-empted for a long time by an higher-priority task /// during an `enqueue` or `dequeue` operation, it is possible that the queue ends-up @@ -230,7 +231,8 @@ impl QueueInner { /// let view: &QueueView = queue.as_view(); /// ``` /// - /// It is often preferable to do the same through type coerction, since `Queue` implements `Unsize>`: + /// It is often preferable to do the same through type coerction, since `Queue` implements + /// `Unsize>`: /// /// ```rust /// # use heapless::mpmc::{Queue, QueueView}; @@ -251,7 +253,8 @@ impl QueueInner { /// let view: &mut QueueView = queue.as_mut_view(); /// ``` /// - /// It is often preferable to do the same through type coerction, since `Queue` implements `Unsize>`: + /// It is often preferable to do the same through type coerction, since `Queue` implements + /// `Unsize>`: /// /// ```rust /// # use heapless::mpmc::{Queue, QueueView}; diff --git a/src/pool.rs b/src/pool.rs index d4b94e110b..2722c0abd4 100644 --- a/src/pool.rs +++ b/src/pool.rs @@ -37,8 +37,8 @@ //! ``` //! //! - measurement method: the cycle counter (CYCCNT) register was sampled each time a breakpoint -//! (`bkpt`) was hit. the difference between the "after" and the "before" value of CYCCNT yields the -//! execution time in clock cycles. +//! (`bkpt`) was hit. the difference between the "after" and the "before" value of CYCCNT yields +//! the execution time in clock cycles. //! //! | API | clock cycles | //! |------------------------------|--------------| diff --git a/src/pool/boxed.rs b/src/pool/boxed.rs index 59dff30951..2c60315ad6 100644 --- a/src/pool/boxed.rs +++ b/src/pool/boxed.rs @@ -407,8 +407,7 @@ impl Default for BoxBlock { #[cfg(test)] mod tests { use core::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; - use std::ptr::addr_of_mut; - use std::thread; + use std::{ptr::addr_of_mut, thread}; use super::*; diff --git a/src/pool/treiber.rs b/src/pool/treiber.rs index 02f95f02b9..812a685e71 100644 --- a/src/pool/treiber.rs +++ b/src/pool/treiber.rs @@ -25,7 +25,8 @@ where /// # Safety /// - `node` must be a valid pointer - /// - aliasing rules must be enforced by the caller. e.g, the same `node` may not be pushed more than once + /// - aliasing rules must be enforced by the caller. e.g, the same `node` may not be pushed more + /// than once pub unsafe fn push(&self, node: NonNullPtr) { impl_::push(self, node); } diff --git a/src/pool/treiber/cas.rs b/src/pool/treiber/cas.rs index e74e24d9a8..f77f8cfc4c 100644 --- a/src/pool/treiber/cas.rs +++ b/src/pool/treiber/cas.rs @@ -241,13 +241,16 @@ where // | | push(p) | (1, 2) -> (1, 3) -> (1, 1) | // | try_pop()::cas(p, p.next) | | (1, 1) | // - // As can be seen, the `cas` operation succeeds, wrongly removing pointer `3` from the stack. + // As can be seen, the `cas` operation succeeds, wrongly removing pointer `3` from + // the stack. // - // By incrementing the tag before returning the pointer, it cannot be pushed again with the, - // same tag, preventing the `try_pop()::cas(p, p.next)` operation from succeeding. + // By incrementing the tag before returning the pointer, it cannot be pushed again + // with the, same tag, preventing the `try_pop()::cas(p, p.next)` + // operation from succeeding. // - // With this fix, `try_pop()` in thread 2 returns `(2, 2)` and the comparison between - // `(1, 2)` and `(2, 2)` fails, restarting the loop and correctly removing the new top: + // With this fix, `try_pop()` in thread 2 returns `(2, 2)` and the comparison + // between `(1, 2)` and `(2, 2)` fails, restarting the loop and + // correctly removing the new top: // // | Thread 1 | Thread 2 | Stack | // |-------------------------------|-------------------------|------------------------------| diff --git a/src/sorted_linked_list.rs b/src/sorted_linked_list.rs index 0b40b454e6..2190916a27 100644 --- a/src/sorted_linked_list.rs +++ b/src/sorted_linked_list.rs @@ -26,12 +26,14 @@ //! //! [`BinaryHeap`]: `crate::binary_heap::BinaryHeap` -use core::cmp::Ordering; -use core::fmt; -use core::marker::PhantomData; -use core::mem::MaybeUninit; -use core::ops::{Deref, DerefMut}; -use core::ptr; +use core::{ + cmp::Ordering, + fmt, + marker::PhantomData, + mem::MaybeUninit, + ops::{Deref, DerefMut}, + ptr, +}; #[cfg(feature = "zeroize")] use zeroize::Zeroize; @@ -43,18 +45,24 @@ mod storage { /// /// There's two implementations available: /// - /// - [`OwnedSortedLinkedListStorage`]: stores the data in an array `[T; N]` whose size is known at compile time. + /// - [`OwnedSortedLinkedListStorage`]: stores the data in an array `[T; N]` whose size is known + /// at compile time. /// - [`ViewSortedLinkedListStorage`]: stores the data in an unsized `[T]`. /// - /// This allows [`SortedLinkedList`] to be generic over either sized or unsized storage. The [`sorted_linked_list`](super) - /// module contains a [`SortedLinkedListInner`] struct that's generic on [`SortedLinkedListStorage`], - /// and two type aliases for convenience: + /// This allows [`SortedLinkedList`] to be generic over either sized or unsized storage. The + /// [`sorted_linked_list`](super) module contains a [`SortedLinkedListInner`] struct that's + /// generic on [`SortedLinkedListStorage`], and two type aliases for convenience: /// - /// - [`SortedLinkedList`](super::SortedLinkedList) = `SortedLinkedListInner>` - /// - [`SortedLinkedListView`](super::SortedLinkedListView) = `SortedLinkedListInner>` + /// - [`SortedLinkedList`](super::SortedLinkedList) = `SortedLinkedListInner>` + /// - [`SortedLinkedListView`](super::SortedLinkedListView) = `SortedLinkedListInner>` /// - /// `SortedLinkedList` can be unsized into `SortedLinkedListView`, either by unsizing coercions such as `&mut SortedLinkedList -> &mut SortedLinkedListView` or - /// `Box -> Box`, or explicitly with [`.as_view()`](super::SortedLinkedList::as_view) or [`.as_mut_view()`](super::SortedLinkedList::as_mut_view). + /// `SortedLinkedList` can be unsized into `SortedLinkedListView`, either by unsizing coercions + /// such as `&mut SortedLinkedList -> &mut SortedLinkedListView` or `Box + /// -> Box`, or explicitly with + /// [`.as_view()`](super::SortedLinkedList::as_view) or + /// [`.as_mut_view()`](super::SortedLinkedList::as_mut_view). /// /// This trait is sealed, so you cannot implement it for your own types. You can only use /// the implementations provided by this crate. @@ -66,7 +74,8 @@ mod storage { pub trait SortedLinkedListStorage: SortedLinkedListSealedStorage {} pub trait SortedLinkedListSealedStorage { - // part of the sealed trait so that no trait is publicly implemented by `OwnedSortedLinkedListStorage` besides `Storage` + // part of the sealed trait so that no trait is publicly implemented by + // `OwnedSortedLinkedListStorage` besides `Storage` fn borrow(&self) -> &[Node]; fn borrow_mut(&mut self) -> &mut [Node]; fn as_view( @@ -88,7 +97,8 @@ mod storage { pub(crate) buffer: T, } - /// Implementation of [`SortedLinkedListStorage`] that stores the data in an array `[T; N]` whose size is known at compile time. + /// Implementation of [`SortedLinkedListStorage`] that stores the data in an array `[T; N]` + /// whose size is known at compile time. pub type OwnedSortedLinkedListStorage = SortedLinkedListStorageInner<[Node; N]>; /// Implementation of [`SortedLinkedListStorage`] that stores the data in an unsized `[T]`. @@ -200,10 +210,11 @@ pub struct Node { next: Idx, } -/// Base struct for [`SortedLinkedList`] and [`SortedLinkedListView`], generic over the [`SortedLinkedListStorage`]. +/// Base struct for [`SortedLinkedList`] and [`SortedLinkedListView`], generic over the +/// [`SortedLinkedListStorage`]. /// -/// In most cases you should use [`SortedLinkedList`] or [`SortedLinkedListView`] directly. Only use this -/// struct if you want to write code that's generic over both. +/// In most cases you should use [`SortedLinkedList`] or [`SortedLinkedListView`] directly. Only use +/// this struct if you want to write code that's generic over both. pub struct SortedLinkedListInner where Idx: LenType, diff --git a/src/spsc.rs b/src/spsc.rs index 271f5a4d6d..6eb6fde4d7 100644 --- a/src/spsc.rs +++ b/src/spsc.rs @@ -79,7 +79,8 @@ //! //! # Benchmarks //! -//! Measured on an ARM Cortex-M3 core running at 8 MHz and with zero flash wait cycles, compiled with `-C opt-level=3`: +//! Measured on an ARM Cortex-M3 core running at 8 MHz and with zero flash wait cycles, compiled +//! with `-C opt-level=3`: //! //! | Method | Time | //! |:-------------------------------|-----:| @@ -91,8 +92,8 @@ //! - All execution times are in clock cycles (1 clock cycle = 125 ns). //! - Execution time is *dependent* on `mem::size_of::()`, as both operations include //! `ptr::read::()` or `ptr::write::()` in their successful path. -//! - The numbers reported correspond to the successful path, i.e. `dequeue` returning `Some` -//! and `enqueue` returning `Ok`. +//! - The numbers reported correspond to the successful path, i.e. `dequeue` returning `Some` and +//! `enqueue` returning `Ok`. //! //! # References //! @@ -125,7 +126,8 @@ pub struct QueueInner { pub(crate) buffer: S::Buffer>>, } -/// A statically allocated single-producer, single-consumer queue with a capacity of `N - 1` elements. +/// A statically allocated single-producer, single-consumer queue with a capacity of `N - 1` +/// elements. /// ///
/// @@ -138,7 +140,8 @@ pub type Queue = QueueInner>; /// A [`Queue`] with dynamic capacity. /// -/// [`Queue`] coerces to `QueueView`. `QueueView` is `!Sized`, meaning it can only ever be used by reference. +/// [`Queue`] coerces to `QueueView`. `QueueView` is `!Sized`, meaning it can only ever be used by +/// reference. pub type QueueView = QueueInner; impl Queue { diff --git a/src/storage.rs b/src/storage.rs index 2c430601f2..4151760e04 100644 --- a/src/storage.rs +++ b/src/storage.rs @@ -76,15 +76,17 @@ pub(crate) trait SealedStorage { /// - [`Vec`](crate::vec::Vec) = `VecInner>` /// - [`VecView`](crate::vec::VecView) = `VecInner` /// -/// `Vec` can be unsized into `VecView`, either by unsizing coercions such as `&mut Vec -> &mut VecView` or -/// `Box -> Box`, or explicitly with [`.as_view()`](crate::vec::Vec::as_view) or [`.as_mut_view()`](crate::vec::Vec::as_mut_view). +/// `Vec` can be unsized into `VecView`, either by unsizing coercions such as `&mut Vec -> &mut +/// VecView` or `Box -> Box`, or explicitly with +/// [`.as_view()`](crate::vec::Vec::as_view) or [`.as_mut_view()`](crate::vec::Vec::as_mut_view). /// /// This trait is sealed, so you cannot implement it for your own types. You can only use /// the implementations provided by this crate. #[allow(private_bounds)] pub trait Storage: SealedStorage {} -/// Implementation of [`Storage`] that stores the data in an array `[T; N]` whose size is known at compile time. +/// Implementation of [`Storage`] that stores the data in an array `[T; N]` whose size is known at +/// compile time. pub enum OwnedStorage {} impl Storage for OwnedStorage {} impl SealedStorage for OwnedStorage { diff --git a/src/string/mod.rs b/src/string/mod.rs index 207d35c6a0..6ee6a056d8 100644 --- a/src/string/mod.rs +++ b/src/string/mod.rs @@ -14,10 +14,10 @@ use core::{ #[cfg(feature = "zeroize")] use zeroize::Zeroize; -use crate::CapacityError; use crate::{ len_type::LenType, vec::{OwnedVecStorage, Vec, VecInner, ViewVecStorage}, + CapacityError, }; mod drain; @@ -67,15 +67,17 @@ mod storage { /// - [`OwnedStorage`]: stores the data in an array whose size is known at compile time. /// - [`ViewStorage`]: stores the data in an unsized slice /// - /// This allows [`String`] to be generic over either sized or unsized storage. The [`string`](super) - /// module contains a [`StringInner`] struct that's generic on [`StringStorage`], - /// and two type aliases for convenience: + /// This allows [`String`] to be generic over either sized or unsized storage. The + /// [`string`](super) module contains a [`StringInner`] struct that's generic on + /// [`StringStorage`], and two type aliases for convenience: /// /// - [`String`](crate::string::String) = `StringInner>` /// - [`StringView`](crate::string::StringView) = `StringInner>` /// - /// `String` can be unsized into `StrinsgView`, either by unsizing coercions such as `&mut String -> &mut StringView` or - /// `Box -> Box`, or explicitly with [`.as_view()`](crate::string::String::as_view) or [`.as_mut_view()`](crate::string::String::as_mut_view). + /// `String` can be unsized into `StrinsgView`, either by unsizing coercions such as `&mut + /// String -> &mut StringView` or `Box -> Box`, or explicitly with + /// [`.as_view()`](crate::string::String::as_view) or + /// [`.as_mut_view()`](crate::string::String::as_mut_view). /// /// This trait is sealed, so you cannot implement it for your own types. You can only use /// the implementations provided by this crate. @@ -136,7 +138,8 @@ mod storage { pub use storage::StringStorage; -/// Implementation of [`StringStorage`] that stores the data in an array whose size is known at compile time. +/// Implementation of [`StringStorage`] that stores the data in an array whose size is known at +/// compile time. pub type OwnedStorage = OwnedVecStorage; /// Implementation of [`StringStorage`] that stores the data in an unsized slice. pub type ViewStorage = ViewVecStorage; @@ -375,7 +378,8 @@ impl StringInner { /// let view: &StringView = s.as_view(); /// ``` /// - /// It is often preferable to do the same through type coerction, since `String` implements `Unsize`: + /// It is often preferable to do the same through type coerction, since `String` implements + /// `Unsize`: /// /// ```rust /// # use heapless::string::{String, StringView}; @@ -396,7 +400,8 @@ impl StringInner { /// let view: &mut StringView = s.as_mut_view(); /// ``` /// - /// It is often preferable to do the same through type coerction, since `String` implements `Unsize`: + /// It is often preferable to do the same through type coerction, since `String` implements + /// `Unsize`: /// /// ```rust /// # use heapless::string::{String, StringView}; @@ -1039,10 +1044,10 @@ pub fn format( /// /// There are two possible error cases. Both return the unit type [`core::fmt::Error`]. /// -/// - In case the formatting exceeds the string's capacity. This error does not exist in -/// the standard library as the string would just grow. -/// - If a formatting trait implementation returns an error. The standard library panics -/// in this case. +/// - In case the formatting exceeds the string's capacity. This error does not exist in the +/// standard library as the string would just grow. +/// - If a formatting trait implementation returns an error. The standard library panics in this +/// case. /// /// # Examples /// diff --git a/src/vec/drain.rs b/src/vec/drain.rs index 69af854e24..eb03a8a1f7 100644 --- a/src/vec/drain.rs +++ b/src/vec/drain.rs @@ -114,8 +114,9 @@ impl Drop for Drain<'_, T, LenT> { let mut vec = self.vec; if size_of::() == 0 { - // ZSTs have no identity, so we don't need to move them around, we only need to drop the correct amount. - // this can be achieved by manipulating the `Vec` length instead of moving values out from `iter`. + // ZSTs have no identity, so we don't need to move them around, we only need to drop the + // correct amount. this can be achieved by manipulating the `Vec` length + // instead of moving values out from `iter`. unsafe { let vec = vec.as_mut(); let old_len = vec.len(); @@ -127,7 +128,8 @@ impl Drop for Drain<'_, T, LenT> { return; } - // ensure elements are moved back into their appropriate places, even when drop_in_place panics + // ensure elements are moved back into their appropriate places, even when drop_in_place + // panics let _guard = DropGuard(self); if drop_len == 0 { diff --git a/src/vec/mod.rs b/src/vec/mod.rs index 6a9d8e3449..448b22db34 100644 --- a/src/vec/mod.rs +++ b/src/vec/mod.rs @@ -1,11 +1,11 @@ //! A fixed capacity [`Vec`](https://doc.rust-lang.org/std/vec/struct.Vec.html). -use core::borrow; -use core::iter::FusedIterator; -use core::marker::PhantomData; use core::{ + borrow, cmp::Ordering, fmt, hash, + iter::FusedIterator, + marker::PhantomData, mem::{self, ManuallyDrop, MaybeUninit}, ops::{self, Range, RangeBounds}, ptr::{self, NonNull}, @@ -15,8 +15,10 @@ use core::{ #[cfg(feature = "zeroize")] use zeroize::Zeroize; -use crate::len_type::{check_capacity_fits, LenType}; -use crate::CapacityError; +use crate::{ + len_type::{check_capacity_fits, LenType}, + CapacityError, +}; mod drain; @@ -35,7 +37,8 @@ mod storage { /// /// There's two implementations available: /// - /// - [`OwnedVecStorage`]: stores the data in an array `[T; N]` whose size is known at compile time. + /// - [`OwnedVecStorage`]: stores the data in an array `[T; N]` whose size is known at compile + /// time. /// - [`ViewVecStorage`]: stores the data in an unsized `[T]`. /// /// This allows [`Vec`] to be generic over either sized or unsized storage. The [`vec`](super) @@ -45,8 +48,10 @@ mod storage { /// - [`Vec`](crate::vec::Vec) = `VecInner>` /// - [`VecView`](crate::vec::VecView) = `VecInner>` /// - /// `Vec` can be unsized into `VecView`, either by unsizing coercions such as `&mut Vec -> &mut VecView` or - /// `Box -> Box`, or explicitly with [`.as_view()`](crate::vec::Vec::as_view) or [`.as_mut_view()`](crate::vec::Vec::as_mut_view). + /// `Vec` can be unsized into `VecView`, either by unsizing coercions such as `&mut Vec -> &mut + /// VecView` or `Box -> Box`, or explicitly with + /// [`.as_view()`](crate::vec::Vec::as_view) or + /// [`.as_mut_view()`](crate::vec::Vec::as_mut_view). /// /// This trait is sealed, so you cannot implement it for your own types. You can only use /// the implementations provided by this crate. @@ -58,7 +63,8 @@ mod storage { pub trait VecStorage: VecSealedStorage {} pub trait VecSealedStorage { - // part of the sealed trait so that no trait is publicly implemented by `OwnedVecStorage` besides `Storage` + // part of the sealed trait so that no trait is publicly implemented by `OwnedVecStorage` + // besides `Storage` fn borrow(&self) -> &[MaybeUninit]; fn borrow_mut(&mut self) -> &mut [MaybeUninit]; @@ -97,7 +103,8 @@ mod storage { pub(crate) buffer: T, } - /// Implementation of [`VecStorage`] that stores the data in an array `[T; N]` whose size is known at compile time. + /// Implementation of [`VecStorage`] that stores the data in an array `[T; N]` whose size is + /// known at compile time. pub type OwnedVecStorage = VecStorageInner<[MaybeUninit; N]>; /// Implementation of [`VecStorage`] that stores the data in an unsized `[T]`. pub type ViewVecStorage = VecStorageInner<[MaybeUninit]>; @@ -252,7 +259,8 @@ pub struct VecInner + ?Sized> { /// assert_eq!(*vec, [7, 1, 2, 3]); /// ``` /// -/// In some cases, the const-generic might be cumbersome. `Vec` can coerce into a [`VecView`] to remove the need for the const-generic: +/// In some cases, the const-generic might be cumbersome. `Vec` can coerce into a [`VecView`] to +/// remove the need for the const-generic: /// /// ```rust /// use heapless::{Vec, VecView}; @@ -261,18 +269,21 @@ pub struct VecInner + ?Sized> { /// let view: &VecView<_, _> = &vec; /// ``` /// -/// For uncommmon capacity values, or in generic scenarios, you may have to provide the `LenT` generic yourself. +/// For uncommmon capacity values, or in generic scenarios, you may have to provide the `LenT` +/// generic yourself. /// -/// This should be the smallest unsigned integer type that your capacity fits in, or `usize` if you don't want to consider this. +/// This should be the smallest unsigned integer type that your capacity fits in, or `usize` if you +/// don't want to consider this. pub type Vec = VecInner>; /// A [`Vec`] with dynamic capacity /// -/// [`Vec`] coerces to `VecView`. `VecView` is `!Sized`, meaning it can only ever be used by reference. +/// [`Vec`] coerces to `VecView`. `VecView` is `!Sized`, meaning it can only ever be used by +/// reference. /// /// Unlike [`Vec`], `VecView` does not have an `N` const-generic parameter. -/// This has the ergonomic advantage of making it possible to use functions without needing to know at -/// compile-time the size of the buffers used, for example for use in `dyn` traits. +/// This has the ergonomic advantage of making it possible to use functions without needing to know +/// at compile-time the size of the buffers used, for example for use in `dyn` traits. /// /// `VecView` is to `Vec` what `[T]` is to `[T; N]`. /// @@ -418,15 +429,16 @@ impl Vec { /// Casts the `LenT` type to a new type, preserving everything else about the vector. /// - /// This can be useful if you need to pass a `Vec` into a `Vec` for example. + /// This can be useful if you need to pass a `Vec` into a `Vec` for + /// example. /// /// This will check at compile time if the `N` value will fit into `NewLenT`, and error if not. pub fn cast_len_type(self) -> Vec { const { check_capacity_fits::() } let this = ManuallyDrop::new(self); - // SAFETY: Pointer argument is derived from a reference, meeting the safety documented invariants. - // This also prevents double drops by wrapping `self` in `ManuallyDrop`. + // SAFETY: Pointer argument is derived from a reference, meeting the safety documented + // invariants. This also prevents double drops by wrapping `self` in `ManuallyDrop`. Vec { len: NewLenT::from_usize(this.len()), buffer: unsafe { ptr::read(&this.buffer) }, @@ -508,7 +520,8 @@ impl + ?Sized> VecInner { /// let view: &VecView = vec.as_view(); /// ``` /// - /// It is often preferable to do the same through type coerction, since `Vec` implements `Unsize>`: + /// It is often preferable to do the same through type coerction, since `Vec` implements + /// `Unsize>`: /// /// ```rust /// # use heapless::{Vec, VecView}; @@ -528,7 +541,8 @@ impl + ?Sized> VecInner { /// let view: &mut VecView = vec.as_mut_view(); /// ``` /// - /// It is often preferable to do the same through type coerction, since `Vec` implements `Unsize>`: + /// It is often preferable to do the same through type coerction, since `Vec` implements + /// `Unsize>`: /// /// ```rust /// # use heapless::{Vec, VecView}; @@ -723,11 +737,11 @@ impl + ?Sized> VecInner { pub fn truncate(&mut self, len: usize) { // This is safe because: // - // * the slice passed to `drop_in_place` is valid; the `len > self.len` - // case avoids creating an invalid slice, and - // * the `len` of the vector is shrunk before calling `drop_in_place`, - // such that no value will be dropped twice in case `drop_in_place` - // were to panic once (if it panics twice, the program aborts). + // * the slice passed to `drop_in_place` is valid; the `len > self.len` case avoids creating + // an invalid slice, and + // * the `len` of the vector is shrunk before calling `drop_in_place`, such that no value + // will be dropped twice in case `drop_in_place` were to panic once (if it panics twice, + // the program aborts). unsafe { // Note: It's intentional that this is `>` and not `>=`. // Changing it to `>=` has negative performance @@ -1235,8 +1249,9 @@ impl + ?Sized> VecInner { } } if DELETED { - // SAFETY: `deleted_cnt` > 0, so the hole slot must not overlap with current element. - // We use copy for move, and never touch this element again. + // SAFETY: `deleted_cnt` > 0, so the hole slot must not overlap with current + // element. We use copy for move, and never touch this + // element again. unsafe { let hole_slot = p.add((g.processed_len - g.deleted_cnt).into_usize()); ptr::copy_nonoverlapping(cur, hole_slot, 1);