feat(docs): document Fenwick tree (#92)

Author: scriptandcompile

src/data_structures/fenwick_tree.rs

@@ -1,40 +1,135 @@
 use std::ops::{Add, AddAssign};
 
-/// Fenwick Tree / Binary Indexed Tree
-/// Consider we have an array arr[0 . . . n-1]. We would like to
+/// A Fenwick Tree (also known as a Binary Indexed Tree) is a data structure
+/// that can efficiently update elements and calculate prefix sums in a table of numbers.
+///
+/// If we have an array arr[0 . . . n-1]. We would like to:
 /// 1. Compute the sum of the first i elements.
-/// 2. Modify the value of a specified element of the array arr[i] = x where 0 <= i <= n-1.Fenwick tree
+/// 2. Modify the value of a specified element of the array arr[i] = x
+///    where 0 <= i <= n-1.
+///
+/// A simple solution is to run a loop from 0 to i-1 and calculate the sum of the elements.
+/// To update a value, simply do arr[i] = x. The first operation takes O(n) time and the
+/// second operation takes O(1) time. Another simple solution is to create an extra array and
+/// store the sum of the first i elements at the i-th index in this new array. The sum of a given
+/// range can be calculated in O(1) time, but the update operation takes O(n) time now. This works
+/// well if the number of query operations is large and the number of update operations is small.
+///
+/// The Fenwick tree provides a way to represent an array of numbers and perform two operations
+/// in O(log n) time.
+///
+/// The two operations are:
+/// 1. Update: Given a number x and an index i, we need to add x to the i-th element.
+/// 2. Query: Given an index i, we need to calculate the prefix sum of the first i elements.
+///
+/// The Fenwick tree is represented as an array of n elements. The tree structure allows us to
+/// perform efficient queries and updates. The tree is constructed in such a way that the value
+/// of each node is the sum of the values of the nodes in its subtree.
+///
 pub struct FenwickTree<T: Add + AddAssign + Copy + Default> {
     data: Vec<T>,
 }
 
 impl<T: Add<Output = T> + AddAssign + Copy + Default> FenwickTree<T> {
-    /// construct a new FenwickTree with given length
+    /// Create a new FenwickTree with length `len`
+    ///
+    /// # Arguments
+    ///
+    /// * `len` - The length of the FenwickTree
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rust_algorithms::data_structures::FenwickTree;
+    ///
+    /// let mut ft = FenwickTree::with_len(10);
+    /// ft.add(0, 1);
+    /// ft.add(1, 2);
+    ///
+    /// assert_eq!(ft.prefix_sum(0), 1);
+    /// assert_eq!(ft.prefix_sum(1), 3);
+    /// ```
     pub fn with_len(len: usize) -> Self {
         FenwickTree {
             data: vec![T::default(); len + 1],
         }
     }
 
-    /// add `val` to `idx`
+    /// Add `val` to the `i`-th element
+    ///
+    /// # Arguments
+    ///
+    /// * `i` - The index of the element to add `val` to
+    /// * `val` - The value to add to the `i`-th element
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rust_algorithms::data_structures::FenwickTree;
+    ///
+    /// let mut ft = FenwickTree::with_len(10);
+    /// ft.add(0, 3);
+    /// ft.add(1, 2);
+    ///
+    /// assert_eq!(ft.prefix_sum(0), 3);
+    /// assert_eq!(ft.prefix_sum(1), 5);
+    /// ```
     pub fn add(&mut self, i: usize, val: T) {
         assert!(i < self.data.len());
+
         let mut i = i + 1;
+
         while i < self.data.len() {
             self.data[i] += val;
             i += lowbit(i);
         }
     }
 
-    /// get the sum of [0, i]
+    /// Get the prefix sum of the first `i` elements
+    ///
+    /// # Arguments
+    ///
+    /// * `i` - The index of the last element to calculate the prefix sum of
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rust_algorithms::data_structures::FenwickTree;
+    ///
+    /// let mut ft = FenwickTree::with_len(10);
+    /// ft.add(0, 1);
+    /// ft.add(1, 2);
+    /// ft.add(2, 3);
+    /// ft.add(3, 4);
+    /// ft.add(4, 5);
+    /// ft.add(5, 6);
+    /// ft.add(6, 7);
+    /// ft.add(7, 8);
+    /// ft.add(8, 9);
+    /// ft.add(9, 10);
+    ///
+    /// assert_eq!(ft.prefix_sum(0), 1);
+    /// assert_eq!(ft.prefix_sum(1), 3);
+    /// assert_eq!(ft.prefix_sum(2), 6);
+    /// assert_eq!(ft.prefix_sum(3), 10);
+    /// assert_eq!(ft.prefix_sum(4), 15);
+    /// assert_eq!(ft.prefix_sum(5), 21);
+    /// assert_eq!(ft.prefix_sum(6), 28);
+    /// assert_eq!(ft.prefix_sum(7), 36);
+    /// assert_eq!(ft.prefix_sum(8), 45);
+    /// assert_eq!(ft.prefix_sum(9), 55);
+    /// ```
     pub fn prefix_sum(&self, i: usize) -> T {
         assert!(i < self.data.len());
+
         let mut i = i + 1;
         let mut res = T::default();
+
         while i > 0 {
             res += self.data[i];
             i -= lowbit(i);
         }
+
         res
     }
 }
@@ -44,32 +139,3 @@ const fn lowbit(x: usize) -> usize {
     let x = x as isize;
     (x & (-x)) as usize
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    #[test]
-    fn it_works() {
-        let mut ft = FenwickTree::with_len(10);
-        ft.add(0, 1);
-        ft.add(1, 2);
-        ft.add(2, 3);
-        ft.add(3, 4);
-        ft.add(4, 5);
-        ft.add(5, 6);
-        ft.add(6, 7);
-        ft.add(7, 8);
-        ft.add(8, 9);
-        ft.add(9, 10);
-        assert_eq!(ft.prefix_sum(0), 1);
-        assert_eq!(ft.prefix_sum(1), 3);
-        assert_eq!(ft.prefix_sum(2), 6);
-        assert_eq!(ft.prefix_sum(3), 10);
-        assert_eq!(ft.prefix_sum(4), 15);
-        assert_eq!(ft.prefix_sum(5), 21);
-        assert_eq!(ft.prefix_sum(6), 28);
-        assert_eq!(ft.prefix_sum(7), 36);
-        assert_eq!(ft.prefix_sum(8), 45);
-        assert_eq!(ft.prefix_sum(9), 55);
-    }
-}