Update the documentation for dsu

Author: qryxip

src/dsu.rs

@@ -1,7 +1,21 @@
-/// Implement (union by size) + (path compression)
-/// Reference:
-/// Zvi Galil and Giuseppe F. Italiano,
-/// Data structures and algorithms for disjoint set union problems
+//! A Disjoint set union (DSU).
+
+/// A Disjoint set union (DSU).
+///
+/// Given an undirected graph, it processes the following queries in $O(\alpha(n))$ time (amortized).
+///
+/// - Edge addition
+/// - Deciding whether given two vertices are in the same connected component
+///
+/// Each connected component internally has a representative vertex.
+///
+/// When two connected components are merged by edge addition, one of the two representatives of these connected components becomes the representative of the new connected component.
+///
+/// In the following documentation, let $n$ be size of the DSU.
+// Implement (union by size) + (path compression)
+// Reference:
+// Zvi Galil and Giuseppe F. Italiano,
+// Data structures and algorithms for disjoint set union problems
 pub struct Dsu {
     n: usize,
     // root node: -1 * component size
@@ -10,13 +24,32 @@ pub struct Dsu {
 }
 
 impl Dsu {
-    // 0 <= size <= 10^8 is constrained.
+    /// Creates a new `Dsu`.
+    ///
+    /// # Constraints
+    ///
+    /// - $0 \leq n \leq 10^8$
+    ///
+    /// # Complexity
+    ///
+    /// - $O(n)$
     pub fn new(size: usize) -> Self {
         Self {
             n: size,
             parent_or_size: vec![-1; size],
         }
     }
+
+    /// Adds an edge $(a, b)$.
+    ///
+    /// # Constraints
+    ///
+    /// - $0 \leq a < n$
+    /// - $0 \leq b < n$
+    ///
+    /// # Complexity
+    ///
+    /// - $O(\alpha(n))$ amortized
     pub fn merge(&mut self, a: usize, b: usize) -> usize {
         assert!(a < self.n);
         assert!(b < self.n);
@@ -32,11 +65,31 @@ impl Dsu {
         x
     }
 
+    /// Returns whether the vertices $a$ and $b$ are in the same connected component.
+    ///
+    /// # Constraints
+    ///
+    /// - $0 \leq a < n$
+    /// - $0 \leq b < n$
+    ///
+    /// # Complexity
+    ///
+    /// - $O(\alpha(n))$ amortized
     pub fn same(&mut self, a: usize, b: usize) -> bool {
         assert!(a < self.n);
         assert!(b < self.n);
         self.leader(a) == self.leader(b)
     }
+
+    /// Returns the representative of the connected component that contains the vertex $a$.
+    ///
+    /// # Constraints
+    ///
+    /// - $0 \leq a < n$
+    ///
+    /// # Complexity
+    ///
+    /// - $O(\alpha(n))$ amortized
     pub fn leader(&mut self, a: usize) -> usize {
         assert!(a < self.n);
         if self.parent_or_size[a] < 0 {
@@ -45,11 +98,29 @@ impl Dsu {
         self.parent_or_size[a] = self.leader(self.parent_or_size[a] as usize) as i32;
         self.parent_or_size[a] as usize
     }
+
+    /// Returns the size of the connected component that contains the vertex $a$.
+    ///
+    /// # Constraints
+    ///
+    /// - $0 \leq a < n$
+    ///
+    /// # Complexity
+    ///
+    /// - $O(\alpha(n))$ amortized
     pub fn size(&mut self, a: usize) -> usize {
         assert!(a < self.n);
         let x = self.leader(a);
         -self.parent_or_size[x] as usize
     }
+
+    /// Divides the graph into connected components.
+    ///
+    /// The result may not be ordered.
+    ///
+    /// # Complexity
+    ///
+    /// - $O(\alpha(n))$ amortized
     pub fn groups(&mut self) -> Vec<Vec<usize>> {
         let mut leader_buf = vec![0; self.n];
         let mut group_size = vec![0; self.n];