From fd3eb6b5f400aee39df7c276235638d1ff33b03a Mon Sep 17 00:00:00 2001 From: Jesse Rosenstock Date: Thu, 19 Dec 2024 20:43:10 +0100 Subject: [PATCH] Clarify documentation and add doctests I found the semantics of `push`/`push_increase`/`push_decrease` somewhat unclear, so I reworded the docs and added doctest examples. --- src/priority_queue/mod.rs | 90 +++++++++++++++++++++++++++++++-------- 1 file changed, 73 insertions(+), 17 deletions(-) diff --git a/src/priority_queue/mod.rs b/src/priority_queue/mod.rs index 05d69f7..4009651 100644 --- a/src/priority_queue/mod.rs +++ b/src/priority_queue/mod.rs @@ -332,9 +332,21 @@ where { /// Insert the item-priority pair into the queue. /// - /// If an element equal to `item` was already into the queue, - /// it is updated and the old value of its priority returned in `Some`; - /// otherwise, returns `None`. + /// If an element equal to `item` is already in the queue, its priority + /// is updated and the old priority is returned in `Some`; otherwise, + /// `item` is inserted with `priority` and `None` is returned. + /// + /// # Example + /// ``` + /// # use priority_queue::PriorityQueue; + /// let mut pq = PriorityQueue::new(); + /// assert_eq!(pq.push("Apples", 5), None); + /// assert_eq!(pq.get_priority("Apples"), Some(&5)); + /// assert_eq!(pq.push("Apples", 6), Some(5)); + /// assert_eq!(pq.get_priority("Apples"), Some(&6)); + /// assert_eq!(pq.push("Apples", 4), Some(6)); + /// assert_eq!(pq.get_priority("Apples"), Some(&4)); + /// ``` /// /// Computes in **O(log(N))** time. pub fn push(&mut self, item: I, priority: P) -> Option

{ @@ -371,13 +383,29 @@ where /// /// If an element equal to `item` is already in the queue with a /// lower priority, its priority is increased to the new one - /// without replacing the element and the old priority is returned. - /// Otherwise, the new element is inserted into the queue. - /// - /// Returns `Some` if an element equal to `item` is already in the - /// queue. If its priority is higher then `priority`, the latter is returned back, - /// otherwise, the old priority is contained in the Option. - /// If the item is not in the queue, `None` is returned. + /// without replacing the element and the old priority is returned + /// in `Some`. + /// + /// If an element equal to `item` is already in the queue with an + /// equal or higher priority, its priority is not changed and the + /// `priority` argument is returned in `Some`. + /// + /// If no element equal to `item` is already in the queue, the new + /// element is inserted and `None` is returned. + /// + /// # Example + /// ``` + /// # use priority_queue::PriorityQueue; + /// let mut pq = PriorityQueue::new(); + /// assert_eq!(pq.push_increase("Apples", 5), None); + /// assert_eq!(pq.get_priority("Apples"), Some(&5)); + /// assert_eq!(pq.push_increase("Apples", 6), Some(5)); + /// assert_eq!(pq.get_priority("Apples"), Some(&6)); + /// // Already present with higher priority, so requested (lower) + /// // priority is returned. + /// assert_eq!(pq.push_increase("Apples", 4), Some(4)); + /// assert_eq!(pq.get_priority("Apples"), Some(&6)); + /// ``` /// /// Computes in **O(log(N))** time. pub fn push_increase(&mut self, item: I, priority: P) -> Option

{ @@ -393,13 +421,29 @@ where /// /// If an element equal to `item` is already in the queue with a /// higher priority, its priority is decreased to the new one - /// without replacing the element and the old priority is returned. - /// Otherwise, the new element is inserted into the queue. - /// - /// Returns `Some` if an element equal to `item` is already in the - /// queue. If its priority is lower then `priority`, the latter is returned back, - /// otherwise, the old priority is contained in the Option. - /// If the item is not in the queue, `None` is returned. + /// without replacing the element and the old priority is returned + /// in `Some`. + /// + /// If an element equal to `item` is already in the queue with an + /// equal or lower priority, its priority is not changed and the + /// `priority` argument is returned in `Some`. + /// + /// If no element equal to `item` is already in the queue, the new + /// element is inserted and `None` is returned. + /// + /// # Example + /// ``` + /// # use priority_queue::PriorityQueue; + /// let mut pq = PriorityQueue::new(); + /// assert_eq!(pq.push_decrease("Apples", 5), None); + /// assert_eq!(pq.get_priority("Apples"), Some(&5)); + /// assert_eq!(pq.push_decrease("Apples", 4), Some(5)); + /// assert_eq!(pq.get_priority("Apples"), Some(&4)); + /// // Already present with lower priority, so requested (higher) + /// // priority is returned. + /// assert_eq!(pq.push_decrease("Apples", 6), Some(6)); + /// assert_eq!(pq.get_priority("Apples"), Some(&4)); + /// ``` /// /// Computes in **O(log(N))** time. pub fn push_decrease(&mut self, item: I, priority: P) -> Option

{ @@ -416,6 +460,18 @@ where /// The argument `item` is only used for lookup, and is not used to overwrite the item's data /// in the priority queue. /// + /// # Example + /// ``` + /// # use priority_queue::PriorityQueue; + /// let mut pq = PriorityQueue::new(); + /// assert_eq!(pq.change_priority("Apples", 5), None); + /// assert_eq!(pq.get_priority("Apples"), None); + /// assert_eq!(pq.push("Apples", 6), None); + /// assert_eq!(pq.get_priority("Apples"), Some(&6)); + /// assert_eq!(pq.change_priority("Apples", 4), Some(6)); + /// assert_eq!(pq.get_priority("Apples"), Some(&4)); + /// ``` + /// /// The item is found in **O(1)** thanks to the hash table. /// The operation is performed in **O(log(N))** time. pub fn change_priority(&mut self, item: &Q, new_priority: P) -> Option