Skip to content

Commit d2f7d8c

Browse files
scriptandcompilescriptandcompile
authored
feat(docs): document binary search tree (#90)
1 parent 308803e commit d2f7d8c

File tree

1 file changed

+270
-12
lines changed

1 file changed

+270
-12
lines changed

‎src/data_structures/binary_search_tree.rs

Lines changed: 270 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,35 @@
11
use std::cmp::Ordering;
22
use std::ops::Deref;
33

4-
/// This struct implements as Binary Search Tree (BST), which is a
5-
/// simple data structure for storing sorted data
4+
/// A binary search tree (BST) is a binary tree where each node has at most two children, and the
5+
/// left child is less than the parent, and the right child is greater than the parent. This
6+
/// implementation is a simple BST, and does not have any balancing mechanisms.
7+
///
8+
/// # Examples
9+
///
10+
/// ```rust
11+
/// use rust_algorithms::data_structures::BinarySearchTree;
12+
///
13+
/// let mut tree = BinarySearchTree::new();
14+
/// tree.insert(5);
15+
/// tree.insert(3);
16+
/// tree.insert(7);
17+
/// tree.insert(1);
18+
/// tree.insert(4);
19+
/// tree.insert(6);
20+
/// tree.insert(8);
21+
///
22+
/// assert!(tree.search(&5));
23+
/// assert!(tree.search(&3));
24+
/// assert!(tree.search(&7));
25+
/// assert!(tree.search(&1));
26+
/// assert!(tree.search(&4));
27+
/// assert!(tree.search(&6));
28+
/// assert!(tree.search(&8));
29+
/// assert!(!tree.search(&0));
30+
/// assert!(!tree.search(&2));
31+
/// assert!(!tree.search(&9));
32+
/// ```
633
pub struct BinarySearchTree<T>
734
where
835
T: Ord,
@@ -12,10 +39,24 @@ where
1239
right: Option<Box<BinarySearchTree<T>>>,
1340
}
1441

42+
/// Default implementation for BinarySearchTree
43+
///
44+
/// Creates a new empty BinarySearchTree
1545
impl<T> Default for BinarySearchTree<T>
1646
where
1747
T: Ord,
1848
{
49+
/// Create a new, empty `BinarySearchTree`.
50+
///
51+
/// # Examples
52+
///
53+
/// ```rust
54+
/// use rust_algorithms::data_structures::BinarySearchTree;
55+
///
56+
/// let tree: BinarySearchTree<i32> = BinarySearchTree::default();
57+
///
58+
/// assert!(tree.is_empty());
59+
/// ```
1960
fn default() -> Self {
2061
Self::new()
2162
}
@@ -25,7 +66,17 @@ impl<T> BinarySearchTree<T>
2566
where
2667
T: Ord,
2768
{
28-
/// Create a new, empty BST
69+
/// Create a new, empty `BinarySearchTree`.
70+
///
71+
/// # Examples
72+
///
73+
/// ```rust
74+
/// use rust_algorithms::data_structures::BinarySearchTree;
75+
///
76+
/// let tree: BinarySearchTree<i32> = BinarySearchTree::new();
77+
///
78+
/// assert!(tree.is_empty());
79+
/// ```
2980
pub fn new() -> BinarySearchTree<T> {
3081
BinarySearchTree {
3182
value: None,
@@ -34,8 +85,52 @@ where
3485
}
3586
}
3687

37-
/// Find a value in this tree. Returns True iff value is in this
38-
/// tree, and false otherwise
88+
/// Determines if this tree is empty.
89+
///
90+
/// # Returns
91+
///
92+
/// `true`` if this tree is empty, and `false`` otherwise.
93+
///
94+
/// # Examples
95+
///
96+
/// ```rust
97+
/// use rust_algorithms::data_structures::BinarySearchTree;
98+
///
99+
/// let mut tree = BinarySearchTree::new();
100+
///
101+
/// assert!(tree.is_empty());
102+
/// tree.insert(5);
103+
/// assert!(!tree.is_empty());
104+
/// ```
105+
pub fn is_empty(&self) -> bool {
106+
self.value.is_none()
107+
}
108+
109+
/// Find a value in this tree.
110+
///
111+
/// # Returns
112+
///
113+
/// `true`` if the value is in this tree, and `false` otherwise.
114+
///
115+
/// # Arguments
116+
///
117+
/// * `value` - The value to search for in this tree.
118+
///
119+
/// # Examples
120+
///
121+
/// ```rust
122+
/// use rust_algorithms::data_structures::BinarySearchTree;
123+
///
124+
/// let mut tree = BinarySearchTree::new();
125+
///
126+
/// tree.insert(5);
127+
/// tree.insert(3);
128+
///
129+
/// assert!(tree.search(&5));
130+
/// assert!(tree.search(&3));
131+
/// assert!(!tree.search(&0));
132+
/// assert!(!tree.search(&4));
133+
/// ```
39134
pub fn search(&self, value: &T) -> bool {
40135
match &self.value {
41136
Some(key) => {
@@ -64,12 +159,52 @@ where
64159
}
65160
}
66161

67-
/// Returns a new iterator which iterates over this tree in order
162+
/// Creates an iterator which iterates over this tree in ascending order
163+
///
164+
/// # Examples
165+
///
166+
/// ```rust
167+
/// use rust_algorithms::data_structures::BinarySearchTree;
168+
///
169+
/// let mut tree = BinarySearchTree::new();
170+
/// tree.insert(5);
171+
/// tree.insert(3);
172+
/// tree.insert(7);
173+
///
174+
/// let mut iter = tree.iter();
175+
///
176+
/// assert_eq!(iter.next().unwrap(), &3);
177+
/// assert_eq!(iter.next().unwrap(), &5);
178+
/// assert_eq!(iter.next().unwrap(), &7);
179+
/// assert_eq!(iter.next(), None);
180+
/// ```
68181
pub fn iter(&self) -> impl Iterator<Item = &T> {
69182
BinarySearchTreeIter::new(self)
70183
}
71184

72-
/// Insert a value into the appropriate location in this tree.
185+
/// Inserts a value into the appropriate location in this tree.
186+
///
187+
/// # Arguments
188+
///
189+
/// * `value` - The value to insert into this tree.
190+
///
191+
/// # Examples
192+
///
193+
/// ```rust
194+
/// use rust_algorithms::data_structures::BinarySearchTree;
195+
///
196+
/// let mut tree = BinarySearchTree::new();
197+
///
198+
/// tree.insert(5);
199+
/// tree.insert(3);
200+
/// tree.insert(7);
201+
///
202+
/// assert!(tree.search(&5));
203+
/// assert!(tree.search(&3));
204+
/// assert!(tree.search(&7));
205+
/// assert!(!tree.search(&0));
206+
/// assert!(!tree.search(&4));
207+
/// ```
73208
pub fn insert(&mut self, value: T) {
74209
if self.value.is_none() {
75210
self.value = Some(value);
@@ -97,23 +232,90 @@ where
97232
}
98233
}
99234

100-
/// Returns the smallest value in this tree
235+
/// Gets the smallest value in this tree.
236+
///
237+
/// # Returns
238+
///
239+
/// The smallest value in this tree, or `None` if this tree is empty.
240+
///
241+
/// # Examples
242+
///
243+
/// ```rust
244+
/// use rust_algorithms::data_structures::BinarySearchTree;
245+
///
246+
/// let mut tree = BinarySearchTree::new();
247+
///
248+
/// assert!(tree.minimum().is_none());
249+
///
250+
/// tree.insert(5);
251+
/// tree.insert(3);
252+
/// tree.insert(7);
253+
///
254+
/// assert_eq!(*tree.minimum().unwrap(), 3);
255+
/// ```
101256
pub fn minimum(&self) -> Option<&T> {
102257
match &self.left {
103258
Some(node) => node.minimum(),
104259
None => self.value.as_ref(),
105260
}
106261
}
107262

108-
/// Returns the largest value in this tree
263+
/// Gets the largest value in this tree.
264+
///
265+
/// # Returns
266+
///
267+
/// The largest value in this tree, or `None` if this tree is empty.
268+
///
269+
/// # Examples
270+
///
271+
/// ```rust
272+
/// use rust_algorithms::data_structures::BinarySearchTree;
273+
///
274+
/// let mut tree = BinarySearchTree::new();
275+
///
276+
/// assert!(tree.maximum().is_none());
277+
///
278+
/// tree.insert(5);
279+
/// tree.insert(3);
280+
/// tree.insert(7);
281+
///
282+
/// assert_eq!(*tree.maximum().unwrap(), 7);
283+
/// ```
109284
pub fn maximum(&self) -> Option<&T> {
110285
match &self.right {
111286
Some(node) => node.maximum(),
112287
None => self.value.as_ref(),
113288
}
114289
}
115290

116-
/// Returns the largest value in this tree smaller than value
291+
/// Gets the largest value in this tree smaller than value
292+
///
293+
/// # Arguments
294+
///
295+
/// * `value` - The floor that limits the maximum value returned.
296+
///
297+
/// # Returns
298+
///
299+
/// The largest value in this tree smaller than value, or `None` if this tree is empty
300+
/// or `value` is smaller than any contained value.
301+
///
302+
/// # Examples
303+
///
304+
/// ```rust
305+
/// use rust_algorithms::data_structures::BinarySearchTree;
306+
///
307+
/// let mut tree = BinarySearchTree::new();
308+
///
309+
/// tree.insert(5);
310+
/// tree.insert(3);
311+
/// tree.insert(7);
312+
///
313+
/// assert_eq!(*tree.floor(&5).unwrap(), 5);
314+
/// assert_eq!(*tree.floor(&4).unwrap(), 3);
315+
/// assert_eq!(*tree.floor(&8).unwrap(), 7);
316+
///
317+
/// assert_eq!(tree.floor(&0), None);
318+
/// ```
117319
pub fn floor(&self, value: &T) -> Option<&T> {
118320
match &self.value {
119321
Some(key) => {
@@ -145,7 +347,34 @@ where
145347
}
146348
}
147349

148-
/// Returns the smallest value in this tree larger than value
350+
/// Gets the smallest value in this tree larger than value.
351+
///
352+
/// # Arguments
353+
///
354+
/// * `value` - The ceil that limits the minimum value returned.
355+
///
356+
/// # Returns
357+
///
358+
/// The smallest value in this tree larger than value, or `None` if this tree is empty
359+
/// or `value` is larger than any contained value.
360+
///
361+
/// # Examples
362+
///
363+
/// ```rust
364+
/// use rust_algorithms::data_structures::BinarySearchTree;
365+
///
366+
/// let mut tree = BinarySearchTree::new();
367+
///
368+
/// tree.insert(5);
369+
/// tree.insert(3);
370+
/// tree.insert(7);
371+
///
372+
/// assert_eq!(*tree.ceil(&5).unwrap(), 5);
373+
/// assert_eq!(*tree.ceil(&4).unwrap(), 5);
374+
/// assert_eq!(*tree.ceil(&0).unwrap(), 3);
375+
///
376+
/// assert_eq!(tree.ceil(&8), None);
377+
/// ```
149378
pub fn ceil(&self, value: &T) -> Option<&T> {
150379
match &self.value {
151380
Some(key) => {
@@ -181,6 +410,9 @@ where
181410
}
182411
}
183412

413+
/// Iterator for BinarySearchTree
414+
///
415+
/// Iterates over the tree in ascending order
184416
struct BinarySearchTreeIter<'a, T>
185417
where
186418
T: Ord,
@@ -192,7 +424,7 @@ impl<'a, T> BinarySearchTreeIter<'a, T>
192424
where
193425
T: Ord,
194426
{
195-
pub fn new(tree: &BinarySearchTree<T>) -> BinarySearchTreeIter<T> {
427+
fn new(tree: &BinarySearchTree<T>) -> BinarySearchTreeIter<T> {
196428
let mut iter = BinarySearchTreeIter { stack: vec![tree] };
197429
iter.stack_push_left();
198430
iter
@@ -205,12 +437,38 @@ where
205437
}
206438
}
207439

440+
/// Iterator implementation for BinarySearchTree
441+
///
442+
/// Iterates over the tree in ascending order
208443
impl<'a, T> Iterator for BinarySearchTreeIter<'a, T>
209444
where
210445
T: Ord,
211446
{
212447
type Item = &'a T;
213448

449+
/// Get the next value in the tree
450+
///
451+
/// # Returns
452+
///
453+
/// The next value in the tree, or `None` if the iterator is exhausted.
454+
///
455+
/// # Examples
456+
///
457+
/// ```rust
458+
/// use rust_algorithms::data_structures::BinarySearchTree;
459+
///
460+
/// let mut tree = BinarySearchTree::new();
461+
/// tree.insert(5);
462+
/// tree.insert(3);
463+
/// tree.insert(7);
464+
///
465+
/// let mut iter = tree.iter();
466+
///
467+
/// assert_eq!(iter.next().unwrap(), &3);
468+
/// assert_eq!(iter.next().unwrap(), &5);
469+
/// assert_eq!(iter.next().unwrap(), &7);
470+
/// assert_eq!(iter.next(), None);
471+
/// ```
214472
fn next(&mut self) -> Option<&'a T> {
215473
if self.stack.is_empty() {
216474
None

0 commit comments

Comments
 (0)