diff --git a/src/lib.rs b/src/lib.rs index 2558cfe..5d801a1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -248,7 +248,7 @@ pub trait BinarySearchTree { /// // / \ / \ /// // 1 3 5 7 /// ``` - /// The in_order_vec is: **[&1, &2, &3, &4, &5, &6, &7, &8].** + /// The in_order_vec is: **[&1, &2, &3, &4, &5, &6, &7].** fn in_order_vec(&self) -> Vec<&T>; /// Returns references to the elements of the tree in the order of a **post-order traversal.** @@ -382,6 +382,7 @@ impl IterativeBST { /// // Empty tree is created /// let mut bst: IterativeBST = IterativeBST::new(); /// assert!(bst.is_empty()) + /// ``` pub fn new() -> IterativeBST { IterativeBST { root: None, @@ -460,7 +461,7 @@ impl Display for IterativeBST { impl BinarySearchTree for IterativeBST { /// Returns the total **number of nodes** within the tree. /// - /// # Examples + /// # Example /// /// ```rust /// use bst_rs::{BinarySearchTree, IterativeBST}; @@ -471,56 +472,250 @@ impl BinarySearchTree for IterativeBST { /// bst.insert(3); /// /// assert_eq!(bst.size(), 3); + /// ``` fn size(&self) -> usize { self.size } + /// Returns `true` if the binary search tree contains no nodes. + /// + /// # Examples + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst: IterativeBST = IterativeBST::new(); + /// assert!(bst.is_empty()); + /// ``` fn is_empty(&self) -> bool { self.size == 0 } + /// Returns `true` if the binary search tree contains one or more nodes. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// assert!(bst.is_empty()); + /// + /// bst.insert(2); + /// + /// assert!(bst.is_not_empty()); + /// ``` fn is_not_empty(&self) -> bool { self.size != 0 } + /// Inserts given value as a node. + /// + /// **Duplicate values are _not allowed_**. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// + /// bst.insert(10); + /// bst.insert(10); // Element is not inserted + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(15); + /// bst.insert(25); + /// + /// assert_eq!(bst.size(), 5); + /// ``` fn insert(&mut self, value: T) { if Node::iterative_insert(&mut self.root, value).is_ok() { self.size += 1; } } + /// Returns `true` if the binary search tree contains an element with the given value. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(7); + /// + /// assert!(bst.contains(&5)); + /// assert!(!bst.contains(&10)); + /// ``` fn contains(&self, value: &T) -> bool { Node::iterative_contains(&self.root, value) } + /// Removes the given value. + /// + /// Tree will not be modified if trying to remove element that does not exist. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(7); + /// assert_eq!(bst.size(), 3); + /// + /// bst.remove(&5); + /// bst.remove(&10); // Element is not removed + /// assert_eq!(bst.size(), 2); + /// ``` fn remove(&mut self, value: &T) { if Node::iterative_remove(&mut self.root, value).is_ok() { self.size -= 1; } } + /// Returns a reference to the element or `None` if element does not exist. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(7); + /// + /// assert_eq!(bst.retrieve(&5), Some(&5)); + /// assert_eq!(bst.retrieve(&10), None); + /// ``` fn retrieve(&self, value: &T) -> Option<&T> { Node::iterative_retrieve(&self.root, value) } + /// Returns a mutable reference to the element (see [IterativeBST::retrieve()]) + /// or `None` if element does not exist. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(10); + /// bst.insert(5); + /// + /// let optional_retrieved_value_as_mut = bst.retrieve_as_mut(&5); + /// assert_eq!(optional_retrieved_value_as_mut, Some(&mut 5)); + /// + /// let mut retrieved_value = optional_retrieved_value_as_mut.unwrap(); + /// *retrieved_value = 2; // Change value inside tree to '2' + /// + /// assert_eq!(bst.retrieve_as_mut(&5), None); // 5 does not exist anymore + /// assert_eq!(bst.retrieve_as_mut(&2), Some(&mut 2)); + /// ``` fn retrieve_as_mut(&mut self, value: &T) -> Option<&mut T> { Node::iterative_retrieve_as_mut(&mut self.root, value) } + /// Returns the **height** or `None` if tree is empty. + /// + /// The height is the number of edges between the root and it's furthest leaf node. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = IterativeBST::new(); + /// assert_eq!(bst.height(), None); + /// + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The height is 2. + /// assert_eq!(bst.height(), Some(2)); + /// ``` fn height(&self) -> Option { self.root .as_ref() .map(|_| Node::iterative_height(&self.root)) } + /// Returns a reference to the minimum element of the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// assert_eq!(bst.min(), None); + /// + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(10); + /// + /// assert_eq!(bst.min(), Some(&2)); + /// ``` fn min(&self) -> Option<&T> { Node::iterative_min(&self.root) } + /// Returns a reference to the maximum element of the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// assert_eq!(bst.max(), None); + /// + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(10); + /// + /// assert_eq!(bst.max(), Some(&10)); + /// ``` fn max(&self) -> Option<&T> { Node::iterative_max(&self.root) } + /// Removes and returns the minimum element from the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// assert_eq!(bst.remove_min(), None); + /// + /// bst.insert(2); + /// bst.insert(5); + /// bst.insert(10); + /// + /// assert_eq!(bst.size(), 3); + /// assert_eq!(bst.remove_min(), Some(2)); + /// assert_eq!(bst.size(), 2); + /// ``` fn remove_min(&mut self) -> Option { let removed_min = Node::iterative_remove_min(&mut self.root); if removed_min.is_some() { @@ -529,6 +724,24 @@ impl BinarySearchTree for IterativeBST { removed_min } + /// Removes and returns the maximum element from the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// assert_eq!(bst.remove_max(), None); + /// + /// bst.insert(2); + /// bst.insert(5); + /// bst.insert(10); + /// + /// assert_eq!(bst.size(), 3); + /// assert_eq!(bst.remove_max(), Some(10)); + /// assert_eq!(bst.size(), 2); + /// ``` fn remove_max(&mut self) -> Option { let removed_max = Node::iterative_remove_max(&mut self.root); if removed_max.is_some() { @@ -537,62 +750,450 @@ impl BinarySearchTree for IterativeBST { removed_max } + /// Returns references to the elements of the tree in **ascending order.**` + /// + /// # Important + /// + /// This is function is analogous to [IterativeBST::in_order_vec()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// assert_eq!(bst.asc_order_vec(), vec![&1, &2, &3, &4, &5, &6, &7]); + /// ``` fn asc_order_vec(&self) -> Vec<&T> { self.in_order_vec() } + /// Returns references to the elements of the tree in the order of a **pre-order traversal.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = IterativeBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The pre_order_vec is: [&4, &2, &1, &3, &6, &5, &7] + /// assert_eq!(bst.pre_order_vec(), vec![&4, &2, &1, &3, &6, &5, &7]); + /// ``` fn pre_order_vec(&self) -> Vec<&T> { Node::iterative_pre_order_vec(&self.root) } + /// Returns references to the elements of the tree in the order of an **in-order traversal.** + /// + /// # Important + /// + /// This is function is analogous to [IterativeBST::asc_order_vec()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = IterativeBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The in_order_vec is: [&1, &2, &3, &4, &5, &6, &7] + /// assert_eq!(bst.in_order_vec(), vec![&1, &2, &3, &4, &5, &6, &7]); + /// ``` fn in_order_vec(&self) -> Vec<&T> { Node::iterative_in_order_vec(&self.root) } + /// Returns references to the elements of the tree in the order of a **post-order traversal.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = IterativeBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The post_order_vec is: [&1, &3, &2, &5, &7, &6, &4] + /// assert_eq!(bst.post_order_vec(), vec![&1, &3, &2, &5, &7, &6, &4]); + /// ``` fn post_order_vec(&self) -> Vec<&T> { Node::iterative_post_order_vec(&self.root) } + /// Returns references to the elements of the tree in the order of a **level-order traversal.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = IterativeBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The level_order_vec is: [&4, &2, &6, &1, &3, &5, &7] + /// assert_eq!(bst.level_order_vec(), vec![&4, &2, &6, &1, &3, &5, &7]); + /// ``` fn level_order_vec(&self) -> Vec<&T> { Node::iterative_level_order_vec(&self.root) } - fn asc_order_iter(&self) -> IntoIter<&T> { - self.in_order_iter() - } - - fn pre_order_iter(&self) -> IntoIter<&T> { + /// Returns an iterator over [IterativeBST::asc_order_vec()]. + /// + /// # Important + /// + /// This is function is analogous to [IterativeBST::in_order_iter()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut asc_order_iter = bst.asc_order_iter(); + /// + /// assert_eq!(asc_order_iter.next(), Some(&1)); + /// assert_eq!(asc_order_iter.next(), Some(&2)); + /// assert_eq!(asc_order_iter.next(), Some(&3)); + /// assert_eq!(asc_order_iter.next(), Some(&4)); + /// assert_eq!(asc_order_iter.next(), Some(&5)); + /// assert_eq!(asc_order_iter.next(), None); + /// ``` + fn asc_order_iter(&self) -> IntoIter<&T> { + self.in_order_iter() + } + + /// Returns an iterator over [IterativeBST::pre_order_vec()]. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut pre_order_iter = bst.pre_order_iter(); + /// + /// assert_eq!(pre_order_iter.next(), Some(&3)); + /// assert_eq!(pre_order_iter.next(), Some(&1)); + /// assert_eq!(pre_order_iter.next(), Some(&2)); + /// assert_eq!(pre_order_iter.next(), Some(&4)); + /// assert_eq!(pre_order_iter.next(), Some(&5)); + /// assert_eq!(pre_order_iter.next(), None); + /// ``` + fn pre_order_iter(&self) -> IntoIter<&T> { Node::iterative_pre_order_vec(&self.root).into_iter() } + /// Returns an iterator over [IterativeBST::in_order_vec()]. + /// + /// # Important + /// + /// This is function is analogous to [IterativeBST::asc_order_iter()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut in_order_iter = bst.in_order_iter(); + /// + /// assert_eq!(in_order_iter.next(), Some(&1)); + /// assert_eq!(in_order_iter.next(), Some(&2)); + /// assert_eq!(in_order_iter.next(), Some(&3)); + /// assert_eq!(in_order_iter.next(), Some(&4)); + /// assert_eq!(in_order_iter.next(), Some(&5)); + /// assert_eq!(in_order_iter.next(), None); + /// ``` fn in_order_iter(&self) -> IntoIter<&T> { Node::iterative_in_order_vec(&self.root).into_iter() } + /// Returns an iterator over [IterativeBST::post_order_vec()]. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut post_order_iter = bst.post_order_iter(); + /// + /// assert_eq!(post_order_iter.next(), Some(&2)); + /// assert_eq!(post_order_iter.next(), Some(&1)); + /// assert_eq!(post_order_iter.next(), Some(&5)); + /// assert_eq!(post_order_iter.next(), Some(&4)); + /// assert_eq!(post_order_iter.next(), Some(&3)); + /// assert_eq!(post_order_iter.next(), None); + /// ``` fn post_order_iter(&self) -> IntoIter<&T> { Node::iterative_post_order_vec(&self.root).into_iter() } + /// Returns an iterator over [IterativeBST::level_order_vec()]. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut level_order_iter = bst.level_order_iter(); + /// + /// assert_eq!(level_order_iter.next(), Some(&3)); + /// assert_eq!(level_order_iter.next(), Some(&1)); + /// assert_eq!(level_order_iter.next(), Some(&4)); + /// assert_eq!(level_order_iter.next(), Some(&2)); + /// assert_eq!(level_order_iter.next(), Some(&5)); + /// assert_eq!(level_order_iter.next(), None); + /// ``` fn level_order_iter(&self) -> IntoIter<&T> { Node::iterative_level_order_vec(&self.root).into_iter() } + /// Returns [IterativeBST::asc_order_iter()] **AND** consumes the tree. + /// + /// # Important + /// + /// This is function is analogous to [IterativeBST::into_in_order_iter()] as the + /// underlying behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_asc_order_iter = bst.into_asc_order_iter(); + /// + /// assert_eq!(into_asc_order_iter.next(), Some(1)); + /// assert_eq!(into_asc_order_iter.next(), Some(2)); + /// assert_eq!(into_asc_order_iter.next(), Some(3)); + /// assert_eq!(into_asc_order_iter.next(), Some(4)); + /// assert_eq!(into_asc_order_iter.next(), Some(5)); + /// assert_eq!(into_asc_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_asc_order_iter(self) -> IntoIter { self.into_in_order_iter() } + /// Returns [IterativeBST::pre_order_iter()] **AND** consumes the tree. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_pre_order_iter = bst.into_pre_order_iter(); + /// + /// assert_eq!(into_pre_order_iter.next(), Some(3)); + /// assert_eq!(into_pre_order_iter.next(), Some(1)); + /// assert_eq!(into_pre_order_iter.next(), Some(2)); + /// assert_eq!(into_pre_order_iter.next(), Some(4)); + /// assert_eq!(into_pre_order_iter.next(), Some(5)); + /// assert_eq!(into_pre_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_pre_order_iter(self) -> IntoIter { Node::iterative_consume_pre_order_vec(self.root).into_iter() } + /// Returns [IterativeBST::in_order_iter()] **AND** consumes the tree. + /// + /// # Important + /// + /// This is function is analogous to [IterativeBST::asc_order_iter()] as the + /// underlying behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_in_order_iter = bst.into_in_order_iter(); + /// + /// assert_eq!(into_in_order_iter.next(), Some(1)); + /// assert_eq!(into_in_order_iter.next(), Some(2)); + /// assert_eq!(into_in_order_iter.next(), Some(3)); + /// assert_eq!(into_in_order_iter.next(), Some(4)); + /// assert_eq!(into_in_order_iter.next(), Some(5)); + /// assert_eq!(into_in_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_in_order_iter(self) -> IntoIter { Node::iterative_consume_in_order_vec(self.root).into_iter() } + /// Returns [IterativeBST::post_order_iter()] **AND** consumes the tree. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_post_order_iter = bst.into_post_order_iter(); + /// + /// assert_eq!(into_post_order_iter.next(), Some(2)); + /// assert_eq!(into_post_order_iter.next(), Some(1)); + /// assert_eq!(into_post_order_iter.next(), Some(5)); + /// assert_eq!(into_post_order_iter.next(), Some(4)); + /// assert_eq!(into_post_order_iter.next(), Some(3)); + /// assert_eq!(into_post_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_post_order_iter(self) -> IntoIter { Node::iterative_consume_post_order_vec(self.root).into_iter() } + /// Returns [IterativeBST::level_order_iter()] **AND** consumes the tree. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, IterativeBST}; + /// + /// let mut bst = IterativeBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_level_order_iter = bst.into_level_order_iter(); + /// + /// assert_eq!(into_level_order_iter.next(), Some(3)); + /// assert_eq!(into_level_order_iter.next(), Some(1)); + /// assert_eq!(into_level_order_iter.next(), Some(4)); + /// assert_eq!(into_level_order_iter.next(), Some(2)); + /// assert_eq!(into_level_order_iter.next(), Some(5)); + /// assert_eq!(into_level_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_level_order_iter(self) -> IntoIter { Node::iterative_consume_level_order_vec(self.root).into_iter() } @@ -607,10 +1208,11 @@ impl RecursiveBST { /// /// ```rust /// use bst_rs::{BinarySearchTree, RecursiveBST}; - //t / + /// /// // Empty tree is created /// let mut bst: RecursiveBST = RecursiveBST::new(); /// assert!(bst.is_empty()) + /// ``` pub fn new() -> RecursiveBST { RecursiveBST { root: None, @@ -689,7 +1291,7 @@ impl Display for RecursiveBST { impl BinarySearchTree for RecursiveBST { /// Returns the total **number of nodes** within the tree. /// - /// # Examples + /// # Example /// /// ```rust /// use bst_rs::{BinarySearchTree, RecursiveBST}; @@ -700,18 +1302,63 @@ impl BinarySearchTree for RecursiveBST { /// bst.insert(3); /// /// assert_eq!(bst.size(), 3); + /// ``` fn size(&self) -> usize { self.size } + /// Returns `true` if the binary search tree contains no nodes. + /// + /// # Examples + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst: RecursiveBST = RecursiveBST::new(); + /// assert!(bst.is_empty()); + /// ``` fn is_empty(&self) -> bool { self.size == 0 } + /// Returns `true` if the binary search tree contains one or more nodes. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// assert!(bst.is_empty()); + /// + /// bst.insert(2); + /// + /// assert!(bst.is_not_empty()); + /// ``` fn is_not_empty(&self) -> bool { self.size != 0 } + /// Inserts given value as a node. + /// + /// **Duplicate values are _not allowed_**. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// + /// bst.insert(10); + /// bst.insert(10); // Element is not inserted + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(15); + /// bst.insert(25); + /// + /// assert_eq!(bst.size(), 5); + /// ``` fn insert(&mut self, value: T) { match self.root { None => { @@ -726,6 +1373,21 @@ impl BinarySearchTree for RecursiveBST { } } + /// Returns `true` if the binary search tree contains an element with the given value. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(7); + /// + /// assert!(bst.contains(&5)); + /// assert!(!bst.contains(&10)); + /// ``` fn contains(&self, value: &T) -> bool { match self.root { None => false, @@ -733,12 +1395,46 @@ impl BinarySearchTree for RecursiveBST { } } + /// Removes the given value. + /// + /// Tree will not be modified if trying to remove element that does not exist. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(7); + /// assert_eq!(bst.size(), 3); + /// + /// bst.remove(&5); + /// bst.remove(&10); // Element is not removed + /// assert_eq!(bst.size(), 2); + /// ``` fn remove(&mut self, value: &T) { if Node::recursive_remove(&mut self.root, value).is_ok() { self.size -= 1; } } + /// Returns a reference to the element or `None` if element does not exist. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(7); + /// + /// assert_eq!(bst.retrieve(&5), Some(&5)); + /// assert_eq!(bst.retrieve(&10), None); + /// ``` fn retrieve(&self, value: &T) -> Option<&T> { match self.root { None => None, @@ -746,6 +1442,27 @@ impl BinarySearchTree for RecursiveBST { } } + /// Returns a mutable reference to the element (see [RecursiveBST::retrieve()]) + /// or `None` if element does not exist. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(10); + /// bst.insert(5); + /// + /// let optional_retrieved_value_as_mut = bst.retrieve_as_mut(&5); + /// assert_eq!(optional_retrieved_value_as_mut, Some(&mut 5)); + /// + /// let mut retrieved_value = optional_retrieved_value_as_mut.unwrap(); + /// *retrieved_value = 2; // Change value inside tree to '2' + /// + /// assert_eq!(bst.retrieve_as_mut(&5), None); // 5 does not exist anymore + /// assert_eq!(bst.retrieve_as_mut(&2), Some(&mut 2)); + /// ``` fn retrieve_as_mut(&mut self, value: &T) -> Option<&mut T> { match self.root { None => None, @@ -753,12 +1470,57 @@ impl BinarySearchTree for RecursiveBST { } } + /// Returns the **height** or `None` if tree is empty. + /// + /// The height is the number of edges between the root and it's furthest leaf node. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = RecursiveBST::new(); + /// assert_eq!(bst.height(), None); + /// + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The height is 2. + /// assert_eq!(bst.height(), Some(2)); + /// ``` fn height(&self) -> Option { self.root .as_ref() .map(|_| Node::recursive_height(&self.root)) } + /// Returns a reference to the minimum element of the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// assert_eq!(bst.min(), None); + /// + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(10); + /// + /// assert_eq!(bst.min(), Some(&2)); + /// ``` fn min(&self) -> Option<&T> { match self.root { None => None, @@ -766,6 +1528,22 @@ impl BinarySearchTree for RecursiveBST { } } + /// Returns a reference to the maximum element of the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// assert_eq!(bst.max(), None); + /// + /// bst.insert(5); + /// bst.insert(2); + /// bst.insert(10); + /// + /// assert_eq!(bst.max(), Some(&10)); + /// ``` fn max(&self) -> Option<&T> { match self.root { None => None, @@ -773,6 +1551,24 @@ impl BinarySearchTree for RecursiveBST { } } + /// Removes and returns the minimum element from the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// assert_eq!(bst.remove_min(), None); + /// + /// bst.insert(2); + /// bst.insert(5); + /// bst.insert(10); + /// + /// assert_eq!(bst.size(), 3); + /// assert_eq!(bst.remove_min(), Some(2)); + /// assert_eq!(bst.size(), 2); + /// ``` fn remove_min(&mut self) -> Option { let removed_min = match self.root { None => None, @@ -786,6 +1582,24 @@ impl BinarySearchTree for RecursiveBST { removed_min } + /// Removes and returns the maximum element from the tree or `None` if tree is empty. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// assert_eq!(bst.remove_max(), None); + /// + /// bst.insert(2); + /// bst.insert(5); + /// bst.insert(10); + /// + /// assert_eq!(bst.size(), 3); + /// assert_eq!(bst.remove_max(), Some(10)); + /// assert_eq!(bst.size(), 2); + /// ``` fn remove_max(&mut self) -> Option { let removed_max = match self.root { None => None, @@ -799,88 +1613,476 @@ impl BinarySearchTree for RecursiveBST { removed_max } + /// Returns references to the elements of the tree in **ascending order.**` + /// + /// # Important + /// + /// This is function is analogous to [RecursiveBST::in_order_vec()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// assert_eq!(bst.asc_order_vec(), vec![&1, &2, &3, &4, &5, &6, &7]); + /// ``` fn asc_order_vec(&self) -> Vec<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_in_order_vec(&self.root, &mut elements); elements } + /// Returns references to the elements of the tree in the order of a **pre-order traversal.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = RecursiveBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The pre_order_vec is: [&4, &2, &1, &3, &6, &5, &7] + /// assert_eq!(bst.pre_order_vec(), vec![&4, &2, &1, &3, &6, &5, &7]); + /// ``` fn pre_order_vec(&self) -> Vec<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_pre_order_vec(&self.root, &mut elements); elements } + /// Returns references to the elements of the tree in the order of an **in-order traversal.** + /// + /// # Important + /// + /// This is function is analogous to [RecursiveBST::asc_order_vec()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = RecursiveBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The in_order_vec is: [&1, &2, &3, &4, &5, &6, &7] + /// assert_eq!(bst.in_order_vec(), vec![&1, &2, &3, &4, &5, &6, &7]); + /// ``` fn in_order_vec(&self) -> Vec<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_in_order_vec(&self.root, &mut elements); elements } + /// Returns references to the elements of the tree in the order of a **post-order traversal.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = RecursiveBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The post_order_vec is: [&1, &3, &2, &5, &7, &6, &4] + /// assert_eq!(bst.post_order_vec(), vec![&1, &3, &2, &5, &7, &6, &4]); + /// ``` fn post_order_vec(&self) -> Vec<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_post_order_vec(&self.root, &mut elements); elements } + /// Returns references to the elements of the tree in the order of a **level-order traversal.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// // Given a tree that looks like: + /// // 4 + /// // / \ + /// // 2 6 + /// // / \ / \ + /// // 1 3 5 7 + /// let mut bst = RecursiveBST::new(); + /// bst.insert(4); + /// bst.insert(6); + /// bst.insert(2); + /// bst.insert(7); + /// bst.insert(5); + /// bst.insert(3); + /// bst.insert(1); + /// + /// // The level_order_vec is: [&4, &2, &6, &1, &3, &5, &7] + /// assert_eq!(bst.level_order_vec(), vec![&4, &2, &6, &1, &3, &5, &7]); + /// ``` fn level_order_vec(&self) -> Vec<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_level_order_vec(&self.root, &mut elements); elements } + /// Returns an iterator over [RecursiveBST::asc_order_vec()]. + /// + /// # Important + /// + /// This is function is analogous to [RecursiveBST::in_order_iter()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut asc_order_iter = bst.asc_order_iter(); + /// + /// assert_eq!(asc_order_iter.next(), Some(&1)); + /// assert_eq!(asc_order_iter.next(), Some(&2)); + /// assert_eq!(asc_order_iter.next(), Some(&3)); + /// assert_eq!(asc_order_iter.next(), Some(&4)); + /// assert_eq!(asc_order_iter.next(), Some(&5)); + /// assert_eq!(asc_order_iter.next(), None); + /// ``` fn asc_order_iter(&self) -> IntoIter<&T> { let mut elements = Vec::new(); Node::recursive_in_order_vec(&self.root, &mut elements); elements.into_iter() } + /// Returns an iterator over [RecursiveBST::pre_order_vec()]. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut pre_order_iter = bst.pre_order_iter(); + /// + /// assert_eq!(pre_order_iter.next(), Some(&3)); + /// assert_eq!(pre_order_iter.next(), Some(&1)); + /// assert_eq!(pre_order_iter.next(), Some(&2)); + /// assert_eq!(pre_order_iter.next(), Some(&4)); + /// assert_eq!(pre_order_iter.next(), Some(&5)); + /// assert_eq!(pre_order_iter.next(), None); + /// ``` fn pre_order_iter(&self) -> IntoIter<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_pre_order_vec(&self.root, &mut elements); elements.into_iter() } + /// Returns an iterator over [RecursiveBST::in_order_vec()]. + /// + /// # Important + /// + /// This is function is analogous to [RecursiveBST::asc_order_iter()] as the underlying + /// behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut in_order_iter = bst.in_order_iter(); + /// + /// assert_eq!(in_order_iter.next(), Some(&1)); + /// assert_eq!(in_order_iter.next(), Some(&2)); + /// assert_eq!(in_order_iter.next(), Some(&3)); + /// assert_eq!(in_order_iter.next(), Some(&4)); + /// assert_eq!(in_order_iter.next(), Some(&5)); + /// assert_eq!(in_order_iter.next(), None); + /// ``` fn in_order_iter(&self) -> IntoIter<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_in_order_vec(&self.root, &mut elements); elements.into_iter() } + /// Returns an iterator over [RecursiveBST::post_order_vec()]. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut post_order_iter = bst.post_order_iter(); + /// + /// assert_eq!(post_order_iter.next(), Some(&2)); + /// assert_eq!(post_order_iter.next(), Some(&1)); + /// assert_eq!(post_order_iter.next(), Some(&5)); + /// assert_eq!(post_order_iter.next(), Some(&4)); + /// assert_eq!(post_order_iter.next(), Some(&3)); + /// assert_eq!(post_order_iter.next(), None); + /// ``` fn post_order_iter(&self) -> IntoIter<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_post_order_vec(&self.root, &mut elements); elements.into_iter() } + /// Returns an iterator over [RecursiveBST::level_order_vec()]. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut level_order_iter = bst.level_order_iter(); + /// + /// assert_eq!(level_order_iter.next(), Some(&3)); + /// assert_eq!(level_order_iter.next(), Some(&1)); + /// assert_eq!(level_order_iter.next(), Some(&4)); + /// assert_eq!(level_order_iter.next(), Some(&2)); + /// assert_eq!(level_order_iter.next(), Some(&5)); + /// assert_eq!(level_order_iter.next(), None); + /// ``` fn level_order_iter(&self) -> IntoIter<&T> { let mut elements: Vec<&T> = Vec::new(); Node::recursive_level_order_vec(&self.root, &mut elements); elements.into_iter() } + /// Returns [RecursiveBST::asc_order_iter()] **AND** consumes the tree. + /// + /// # Important + /// + /// This is function is analogous to [RecursiveBST::into_in_order_iter()] as the + /// underlying behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_asc_order_iter = bst.into_asc_order_iter(); + /// + /// assert_eq!(into_asc_order_iter.next(), Some(1)); + /// assert_eq!(into_asc_order_iter.next(), Some(2)); + /// assert_eq!(into_asc_order_iter.next(), Some(3)); + /// assert_eq!(into_asc_order_iter.next(), Some(4)); + /// assert_eq!(into_asc_order_iter.next(), Some(5)); + /// assert_eq!(into_asc_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_asc_order_iter(self) -> IntoIter { self.into_in_order_iter() } + /// Returns [RecursiveBST::pre_order_iter()] **AND** consumes the tree. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_pre_order_iter = bst.into_pre_order_iter(); + /// + /// assert_eq!(into_pre_order_iter.next(), Some(3)); + /// assert_eq!(into_pre_order_iter.next(), Some(1)); + /// assert_eq!(into_pre_order_iter.next(), Some(2)); + /// assert_eq!(into_pre_order_iter.next(), Some(4)); + /// assert_eq!(into_pre_order_iter.next(), Some(5)); + /// assert_eq!(into_pre_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_pre_order_iter(self) -> IntoIter { let mut elements = Vec::new(); Node::recursive_consume_pre_order_vec(self.root, &mut elements); elements.into_iter() } + /// Returns [RecursiveBST::in_order_iter()] **AND** consumes the tree. + /// + /// # Important + /// + /// This is function is analogous to [RecursiveBST::asc_order_iter()] as the + /// underlying behaviour is **_exactly the same_.** + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_in_order_iter = bst.into_in_order_iter(); + /// + /// assert_eq!(into_in_order_iter.next(), Some(1)); + /// assert_eq!(into_in_order_iter.next(), Some(2)); + /// assert_eq!(into_in_order_iter.next(), Some(3)); + /// assert_eq!(into_in_order_iter.next(), Some(4)); + /// assert_eq!(into_in_order_iter.next(), Some(5)); + /// assert_eq!(into_in_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_in_order_iter(self) -> IntoIter { let mut elements = Vec::new(); Node::recursive_consume_in_order_vec(self.root, &mut elements); elements.into_iter() } + /// Returns [RecursiveBST::post_order_iter()] **AND** consumes the tree. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_post_order_iter = bst.into_post_order_iter(); + /// + /// assert_eq!(into_post_order_iter.next(), Some(2)); + /// assert_eq!(into_post_order_iter.next(), Some(1)); + /// assert_eq!(into_post_order_iter.next(), Some(5)); + /// assert_eq!(into_post_order_iter.next(), Some(4)); + /// assert_eq!(into_post_order_iter.next(), Some(3)); + /// assert_eq!(into_post_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_post_order_iter(self) -> IntoIter { let mut elements = Vec::new(); Node::recursive_consume_post_order_vec(self.root, &mut elements); elements.into_iter() } + /// Returns [RecursiveBST::level_order_iter()] **AND** consumes the tree. + /// + /// # Example + /// + /// ```rust + /// use bst_rs::{BinarySearchTree, RecursiveBST}; + /// + /// let mut bst = RecursiveBST::new(); + /// bst.insert(3); + /// bst.insert(4); + /// bst.insert(5); + /// bst.insert(1); + /// bst.insert(2); + /// + /// let mut into_level_order_iter = bst.into_level_order_iter(); + /// + /// assert_eq!(into_level_order_iter.next(), Some(3)); + /// assert_eq!(into_level_order_iter.next(), Some(1)); + /// assert_eq!(into_level_order_iter.next(), Some(4)); + /// assert_eq!(into_level_order_iter.next(), Some(2)); + /// assert_eq!(into_level_order_iter.next(), Some(5)); + /// assert_eq!(into_level_order_iter.next(), None); + /// + /// // bst.insert(10); -> COMPILE ERROR + /// ``` fn into_level_order_iter(self) -> IntoIter { let mut elements = Vec::new(); Node::recursive_consume_level_order_vec(self.root, &mut elements);