Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(cordyceps): fix wrong time complexity notes #430

Merged
merged 3 commits into from
May 5, 2023
Merged

docs(cordyceps): fix wrong time complexity notes #430

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a4ef7c
docs(cordyceps): fix wrong time complexity notes (#430)
hawkw May 5, 2023
7e62e6f
docs(cordyceps): add nicer "Returns" sections (#430)
hawkw May 5, 2023
c551990
Merge branch 'main' into eliza/constant-time
hawkw May 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 64 additions & 18 deletions cordyceps/src/list.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -310,7 +310,7 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
/// This reuses all the nodes from `other` and moves them into `self`. After
/// this operation, `other` becomes empty.
///
/// This operation should compute in *O*(1) time and *O*(1) memory.
/// This operation should complete in *O*(1) time and *O*(1) memory.
pub fn append(&mut self, other: &mut Self) {
// TODO(eliza): this could be rewritten to use `let ... else` when
// that's supported on `cordyceps`' MSRV.
Expand Down Expand Up @@ -345,11 +345,11 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
/// Returns everything after the given index (including the node at that
/// index), or `None` if the index is greater than the list's [length].
///
/// This operation should compute in *O*(*n*) time.
/// This operation should complete in *O*(*n*) time.
///
/// # Returns
///
/// - [`Some`]`(List<T>)` with a new list containing every element after
/// - [`Some`]`(`[`List`]`<T>)` with a new list containing every element after
/// `at`, if `at` <= `self.len()`
/// - [`None`] if `at > self.len()`
///
Expand Down Expand Up @@ -394,10 +394,15 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {

/// Split the list into two at the given index (inclusive).
///
/// Returns everything after the given index (including the node at that
/// index).
/// Every element after the given index, including the node at that
/// index, is removed from this list, and returned as a new list.
///
/// This operation should complete in *O*(*n*) time.
///
/// This operation should compute in *O*(1) time and *O*(1) memory.
/// # Returns
///
/// A new [`List`]`<T>` containing every element after the index `at` in
/// this list.
///
/// # Panics
///
Expand Down Expand Up @@ -520,11 +525,17 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {

/// Removes an item from the tail of the list.
///
/// This operation should compute in *O*(*n*) time.
/// This operation should complete in *O*(1) time.
///
/// This returns a [`Handle`] that owns the popped element. Dropping the
/// [`Handle`] will drop the element.
///
/// # Returns
///
/// - [`Some`]`(T::Handle)` containing the last element of this list, if the
/// list was not empty.
/// - [`None`] if this list is empty.
///
/// [`Handle`]: crate::Linked::Handle
pub fn pop_back(&mut self) -> Option<T::Handle> {
let tail = self.tail?;
Expand Down Expand Up @@ -552,13 +563,19 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
}
}

/// Remove an item from the head of the list.
/// Removes an item from the head of the list.
///
/// This operation should compute in *O*(*n*) time.
/// This operation should complete in *O*(1) time.
///
/// This returns a [`Handle`] that owns the popped element. Dropping the
/// [`Handle`] will drop the element.
///
/// # Returns
///
/// - [`Some`]`(T::Handle)` containing the last element of this list, if the
/// list was not empty.
/// - [`None`] if this list is empty.
///
/// [`Handle`]: crate::Linked::Handle
pub fn pop_front(&mut self) -> Option<T::Handle> {
let head = self.head?;
Expand All @@ -580,7 +597,7 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {

/// Appends an item to the tail of the list.
///
/// This operation should compute in *O*(*n*) time.
/// This operation should complete in *O*(1) time.
///
/// This takes a [`Handle`] that owns the appended `item`. While the element
/// is in the list, it is owned by the list, and will be dropped when the
Expand Down Expand Up @@ -609,7 +626,7 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {

/// Appends an item to the head of the list.
///
/// This operation should compute in *O*(*n*) time.
/// This operation should complete in *O*(1) time.
///
/// This takes a [`Handle`] that owns the appended `item`. While the element
/// is in the list, it is owned by the list, and will be dropped when the
Expand Down Expand Up @@ -641,14 +658,19 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
// tracing::trace!(?self, "push_front: pushed");
}

/// Returns a reference to the first element in the list, or `None`
/// if the list is empty.
/// Returns an immutable reference to the first element in the list.
///
/// This operation should complete in *O*(1) time.
///
/// The node is [`Pin`]ned in memory, as moving it to a different memory
/// location while it is in the list would corrupt the links pointing to
/// that node.
///
/// This operation should complete in *O*(1) time.
/// # Returns
///
/// - [`Some`]`(`[`Pin`]`<&mut T>)` containing a pinned immutable reference to
/// the first element of the list, if the list is non-empty.
/// - [`None`] if the list is empty.
#[must_use]
pub fn front(&self) -> Option<Pin<&T>> {
let head = self.head?;
Expand All @@ -662,14 +684,19 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
Some(pin)
}

/// Returns a mutable reference to the first element in the list, or `None`
/// if the list is empty.
/// Returns a mutable reference to the first element in the list.
///
/// The node is [`Pin`]ned in memory, as moving it to a different memory
/// location while it is in the list would corrupt the links pointing to
/// that node.
///
/// This operation should complete in *O*(1) time.
///
/// # Returns
///
/// - [`Some`]`(`[`Pin`]`<&mut T>)` containing a pinned mutable reference to
/// the first element of the list, if the list is non-empty.
/// - [`None`] if the list is empty.
#[must_use]
pub fn front_mut(&mut self) -> Option<Pin<&mut T>> {
let mut node = self.head?;
Expand All @@ -683,14 +710,19 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
Some(pin)
}

/// Returns a reference to the last element in the list, or `None`
/// if the list is empty.
/// Returns a reference to the last element in the list/
///
/// The node is [`Pin`]ned in memory, as moving it to a different memory
/// location while it is in the list would corrupt the links pointing to
/// that node.
///
/// This operation should complete in *O*(1) time.
///
/// # Returns
///
/// - [`Some`]`(`[`Pin`]`<&T>)` containing a pinned immutable reference to
/// the last element of the list, if the list is non-empty.
/// - [`None`] if the list is empty.
#[must_use]
pub fn back(&self) -> Option<Pin<&T>> {
let node = self.tail?;
Expand All @@ -712,6 +744,12 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {
/// that node.
///
/// This operation should complete in *O*(1) time.
///
/// # Returns
///
/// - [`Some`]`(`[`Pin`]`<&T>)` containing a pinned mutable reference to
/// the last element of the list, if the list is non-empty.
/// - [`None`] if the list is empty.
#[must_use]
pub fn back_mut(&mut self) -> Option<Pin<&mut T>> {
let mut node = self.tail?;
Expand All @@ -727,9 +765,17 @@ impl<T: Linked<Links<T>> + ?Sized> List<T> {

/// Remove an arbitrary node from the list.
///
/// This operation should complete in *O*(1) time.
///
/// This returns a [`Handle`] that owns the popped element. Dropping the
/// [`Handle`] will drop the element.
///
/// # Returns
///
/// - [`Some`]`(T::Handle)` containing a [`Handle`] that owns `item`, if
/// `item` is currently linked into this list.
/// - [`None`] if `item` is not an element of this list.
///
/// [`Handle`]: crate::Linked::Handle
///
/// # Safety
Expand Down