Start adding documentation

pull/3/head
sgoudham 3 years ago
parent 7ce3762ee9
commit 1a6af483f6
Signed by: hammy
GPG Key ID: 44E818FD5457EEA4

@ -1,20 +1,117 @@
//! This crate contains Recursive & Iterative Binary Search Tree Implementations. All common
//! operations are included along with
//! operations are included along with common traversal iterators.
//!
//! It is important to note that [RecursiveBST] is more likely to `blow the stack.`
//! For more information on why that is the case, please read [The Story of Tail Call Optimizations in Rust.](https://seanchen1991.github.io/posts/tco-story/)
//! All elements within the Binary Search Trees _must_ implement the [Ord] trait.
//!
//! # Basic Usage
//! It is also important to note that [RecursiveBST] is more likely to `blow the stack.`
//! For more information on why that is the case, please read have a look at
//! [The Story of Tail Call Optimizations in Rust.](https://seanchen1991.github.io/posts/tco-story/)
//!
//! ## Author Notes
//!
//! I have made this library with the personal goals of learning and solidifying concepts such
//! as ownership, borrowing, generics and lifetimes. I cannot promise that the implementations are
//! particularly efficient, or if they are, it was not at the forefront of my mind.
//!
//! That being said, there are some areas I would love to improve/include:
//! - Write Rust more idiomatically.
//! - Implement a `pretty_print()` function to display the binary search trees nicely.
//! - Implementing the Drop trait for iterative node cleanup.
//! - Pre-allocating space on the heap for nodes to reduce inefficiency of inserts.
//!
//! I'm more than happy to accept (and encourage) contributions if anyone is kind enough to do so.
//!
//! # Quick Start
//!
//! ```rust
//! use bst_rs::{BinarySearchTree, IterativeBST, RecursiveBST};
//!
//! // Create new empty binary search trees
//! let mut iterative_bst = IterativeBST::new();
//! assert!(iterative_bst.is_empty());
//!
//! let mut recursive_bst = RecursiveBST::new();
//! assert!(recursive_bst.is_empty());
//!
//! // Insert elements (no duplicates are allowed)
//! iterative_bst.insert(10);
//! iterative_bst.insert(10); // Element is not inserted
//! iterative_bst.insert(5);
//! iterative_bst.insert(2);
//! iterative_bst.insert(15);
//! iterative_bst.insert(25);
//! assert_eq!(iterative_bst.size(), 5);
//!
//! recursive_bst.insert(10);
//! recursive_bst.insert(10); // Element is not inserted
//! recursive_bst.insert(5);
//! recursive_bst.insert(2);
//! recursive_bst.insert(15);
//! recursive_bst.insert(25);
//! assert_eq!(recursive_bst.size(), 5);
//!
//! // Check if element exists
//! assert!(iterative_bst.contains(&5)); // true
//! assert!(!iterative_bst.contains(&0)); // false
//!
//! assert!(recursive_bst.contains(&5)); // true
//! assert!(!recursive_bst.contains(&0)); // false
//!
//! // Remove elements
//! iterative_bst.remove(&10);
//! iterative_bst.remove(&50); // No change to tree as element does not exist
//! assert_eq!(iterative_bst.size(), 4);
//!
//! recursive_bst.remove(&10);
//! recursive_bst.remove(&50); // No change to tree as element does not exist
//! assert_eq!(recursive_bst.size(), 4);
//!
//! // View pre-order, in-order and post-order traversals
//! assert_eq!(iterative_bst.pre_order_vec(), vec![&15, &5, &2, &25]);
//! assert_eq!(iterative_bst.in_order_vec(), vec![&2, &5, &15, &25]);
//! assert_eq!(iterative_bst.post_order_vec(), vec![&2, &5, &25, &15]);
//!
//! assert_eq!(recursive_bst.pre_order_vec(), vec![&15, &5, &2, &25]);
//! assert_eq!(recursive_bst.in_order_vec(), vec![&2, &5, &15, &25]);
//! assert_eq!(recursive_bst.post_order_vec(), vec![&2, &5, &25, &15]);
//!
//! // Create new IterativeBST
//! // Compare equality of trees
//! assert_eq!(iterative_bst.sorted_vec(), recursive_bst.sorted_vec());
//! assert_ne!(iterative_bst, IterativeBST::new());
//! assert_ne!(recursive_bst, RecursiveBST::new());
//! ```
use std::cmp::Ordering;
use std::fmt::{Debug, Display, Formatter};
use std::vec::IntoIter;
/// A trait containing all the common operations of Binary Search Trees.
///
/// # Examples
/// _Examples are extended from crate level "Quick Start"_
///
/// ```rust
/// use bst_rs::{BinarySearchTree, IterativeBST};
///
/// // Create a new empty Iterative Binary Search Tree
/// let mut new_bst = IterativeBST::new();
/// assert!(new_bst.is_empty());
///
/// // Populate new_bst with 5 elements (no duplicates are allowed)
/// new_bst.insert(10);
/// new_bst.insert(5);
/// new_bst.insert(15);
/// new_bst.insert(18);
/// new_bst.insert(2);
/// assert_eq!(new_bst.size(), 5);
///
/// // We can also create a IterativeBST from vecs and iterators
/// let mut bst_from_vec = IterativeBST::from(vec![10, 5, 15, 18, 2]);
/// let mut bst_from_iter = IterativeBST::from_iter((10..20).map(|node| node > 15));
///
/// // Retrieve the in_order_vec() and sorted_vec() which retrieve the elements in order
/// assert_eq!(bst_from_vec.in_order_vec(), vec![&2, &5, &10, &15, &18]);
/// assert_eq!(bst_from_vec.sorted_vec(), vec![&2, &5, &10, &15, &18]);
pub trait BinarySearchTree<T: Ord> {
fn new() -> Self;
fn size(&self) -> usize;

Loading…
Cancel
Save