Documenting panics

Author: EbTech

src/arq_tree.rs

@@ -60,7 +60,7 @@ where
         }
     }
 
-    /// Performs the endomorphism f on all entries from l to r, inclusive.
+    /// Applies the endomorphism f to all entries from l to r, inclusive.
     pub fn modify(&mut self, mut l: usize, mut r: usize, f: &T::F) {
         l += self.d.len();
         r += self.d.len();
@@ -113,9 +113,9 @@ pub trait ArqSpec {
     fn compose(f: &Self::F, g: &Self::F) -> Self::F;
     /// Require for all f,a,b: apply(f, op(a, b)) = op(apply(f, a), apply(f, b))
     fn apply(f: &Self::F, a: &Self::M) -> Self::M;
-    /// Require for alla,b,c: op(a, op(b, c)) = op(op(a, b), c)
+    /// Require for all a,b,c: op(a, op(b, c)) = op(op(a, b), c)
     fn op(a: &Self::M, b: &Self::M) -> Self::M;
-    /// Require all a: op(a, identity()) = op(identity(), a) = a
+    /// Require for all a: op(a, identity()) = op(identity(), a) = a
     fn identity() -> Self::M;
 }
 
@@ -128,6 +128,10 @@ pub trait ArqSpec {
 /// of a_i. Now check that f_c((a, s)) = (c*s, s) is indeed an endomorphism:
 /// f_c((a,s)+(b,t)) = f_c((a+b,s+t)) = (c*(s+t),s+t) = (c*s,s)+(c*t,t) =
 /// f_c((a,s)) + f_c((b,t)).
+///
+/// # Panics
+///
+/// Associated functions will panic on overflow.
 pub struct AssignAdd;
 
 impl ArqSpec for AssignAdd {

src/graph/connectivity.rs

@@ -9,19 +9,25 @@ use std::cmp::min;
 /// - 2-edge-connected components (2ECC),
 /// - 2-vertex-connected components (2VCC)
 ///
-/// Multiple-edges and self-loops should be correctly handled.
+/// Multiple-edges and self-loops are correctly handled.
 pub struct ConnectivityGraph<'a> {
-    pub graph: &'a Graph, // Immutable graph, frozen for lifetime of this obj.
-    pub cc: Vec<usize>, // Stores id of a vertex's CC, SCC or 2ECC.
-    pub vcc: Vec<usize>, // Stores id of an edge's 2VCC.
+    // Immutable graph, frozen for the lifetime of the ConnectivityGraph object.
+    pub graph: &'a Graph,
+    /// ID of a vertex's CC, SCC or 2ECC (new() documents when each applies).
+    pub cc: Vec<usize>,
+    /// ID of an edge's 2VCC, where applicable.
+    pub vcc: Vec<usize>,
+    /// Total number of CCs, SCCs or 2ECCs, whichever applies.
     pub num_cc: usize,
+    /// Total number of 2VCCs, where applicable.
     pub num_vcc: usize,
 }
 
 impl<'a> ConnectivityGraph<'a> {
     /// Computes the SCCs of a directed graph in reverse topological order, or
     /// the 2ECCs/2VCCS of an undirected graph. Can also get CCs by passing an
-    /// undirected graph using `is_directed == true`.
+    /// undirected graph using `is_directed == true`. Undefined behavior if
+    /// passing a directed graph using `is_directed == false`.
     pub fn new(graph: &'a Graph, is_directed: bool) -> Self {
         let mut connect = Self {
             graph: graph,
@@ -102,7 +108,8 @@ impl<'a> ConnectivityGraph<'a> {
             .collect()
     }
 
-    /// Gets the vertices of a directed acyclic graph (DAG) in topological order.
+    /// Gets the vertices of a directed acyclic graph (DAG) in topological
+    /// order. Undefined behavior if the graph is not a DAG.
     pub fn topological_sort(&self) -> Vec<usize> {
         let mut vertices = (0..self.graph.num_v()).collect::<Vec<_>>();
         vertices.sort_by_key(|&u| self.num_cc - self.cc[u]);

src/graph/flow.rs

@@ -1,12 +1,15 @@
-//! Maximum flows and minimum cuts.
+//! Maximum flows, matchings, and minimum cuts.
 use graph::{Graph, AdjListIterator};
 use std::cmp::min;
 const INF: i64 = 0x3f3f3f3f;
 
 /// Representation of a network flow problem with (optional) costs.
 pub struct FlowGraph {
-    pub graph: Graph, // Owned graph, controlled by this FlowGraph object.
+    /// Owned graph, managed by this FlowGraph object.
+    pub graph: Graph,
+    /// Edge capacities.
     pub cap: Vec<i64>,
+    /// Edge cost per unit flow.
     pub cost: Vec<i64>,
 }
 
@@ -30,9 +33,14 @@ impl FlowGraph {
         self.graph.add_undirected_edge(u, v);
     }
 
-    /// Dinic's maximum flow / Hopcroft-Karp maximum bipartite matching:
+    /// Dinic's algorithm to find the maximum flow from s to t where s != t.
+    /// Generalizes the Hopcroft-Karp maximum bipartite matching algorithm.
     /// V^2E in general, min(V^(2/3),sqrt(E))E when all edges are unit capacity,
     /// sqrt(V)E when all vertices are unit capacity as in bipartite graphs.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the maximum flow is 2^63 or larger.
     pub fn dinic(&self, s: usize, t: usize) -> i64 {
         let mut flow = vec![0; self.graph.num_e()];
         let mut max_flow = 0;
@@ -110,7 +118,12 @@ impl FlowGraph {
             .collect()
     }
 
-    /// Minimum cost maximum flow, assuming no negative-cost cycles.
+    /// Among all s-t maximum flows, finds one with minimum cost, assuming
+    /// s != t and no negative-cost cycles.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the flow or cost overflow a 64-bit signed integer.
     pub fn mcf(&self, s: usize, t: usize) -> (i64, i64) {
         let mut pot = vec![0; self.graph.num_v()];
 
@@ -139,8 +152,8 @@ impl FlowGraph {
         (min_cost, max_flow)
     }
 
-    // Maintains Johnson's potentials to prevent negative-weight residual edges.
-    // This enables running Dijkstra instead of the slower Bellman-Ford.
+    // Maintains Johnson's potentials to prevent negative-cost residual edges.
+    // This allows running Dijkstra instead of the slower Bellman-Ford.
     fn mcf_search(&self, s: usize, flow: &[i64], pot: &mut [i64]) -> Vec<Option<usize>> {
         let mut vis = vec![false; self.graph.num_v()];
         let mut dist = vec![INF; self.graph.num_v()];

src/graph/mod.rs

@@ -1,4 +1,8 @@
-//! Basic graph library without explicit support for deletion.
+//! Basic graph module without explicit support for deletion.
+//!
+//! # Panics
+//!
+//! All methods will panic if given an out-of-bounds element index.
 pub mod flow;
 pub mod connectivity;
 
@@ -76,9 +80,10 @@ impl Graph {
         self.add_edge(v, u);
     }
 
-    /// If we think of each even-numbered vertex as a variable, and its successor
-    /// as its negation, then we can build the implication graph corresponding
-    /// to any 2-CNF formula. Note that u||v == !u -> v == !v -> u.
+    /// If we think of each even-numbered vertex as a variable, and its
+    /// odd-numbered successor as its negation, then we can build the
+    /// implication graph corresponding to any 2-CNF formula.
+    /// Note that u||v == !u -> v == !v -> u.
     pub fn add_two_sat_clause(&mut self, u: usize, v: usize) {
         self.add_edge(u ^ 1, v);
         self.add_edge(v ^ 1, u);
@@ -92,9 +97,10 @@ impl Graph {
         }
     }
 
-    /// Finds the sequence of edges in an Euler path starting from u, assuming it
-    /// exists and that the graph is directed. To extend this to undirected
-    /// graphs, keep track of a visited array to skip the reverse edge.
+    /// Finds the sequence of edges in an Euler path starting from u, assuming
+    /// it exists and that the graph is directed. Undefined behavior if this
+    /// precondition is violated. To extend this to undirected graphs, maintain
+    /// a visited array to skip the reverse edge.
     pub fn euler_path(&self, u: usize) -> Vec<usize> {
         let mut adj_iters = (0..self.num_v())
             .map(|u| self.adj_list(u))
@@ -105,8 +111,8 @@ impl Graph {
         edges
     }
 
-    // Helper function used by euler_path. Note that we can't consume the
-    // adjacency list in a for loop because recursive calls may need it.
+    // Helper function used by euler_path. Note that we can't use a for-loop
+    // that would consume the adjacency list as recursive calls may need it.
     fn euler_recurse(&self, u: usize, adj: &mut [AdjListIterator], edges: &mut Vec<usize>) {
         while let Some((e, v)) = adj[u].next() {
             self.euler_recurse(v, adj, edges);

src/math.rs

@@ -1,7 +1,12 @@
 //! Number-theoretic utilities for contest problems.
 
 /// Modular exponentiation by repeated squaring: returns base^exp % m.
-pub fn mod_pow(mut base: i64, mut exp: i64, m: i64) -> i64 {
+///
+/// # Panics
+///
+/// Panics if m == 0. May panic on overflow if m * m > 2^63.
+pub fn mod_pow(mut base: i64, mut exp: u32, m: u32) -> i64 {
+    let m = m as i64;
     let mut result = 1 % m;
     while exp > 0 {
         if exp % 2 == 1 {
@@ -24,6 +29,10 @@ pub fn extended_gcd(a: i64, b: i64) -> (i64, i64, i64) {
 }
 
 /// Assuming a != 0, finds smallest y >= 0 such that ax + by = c.
+///
+/// # Panics
+///
+/// Panics if a == 0.
 pub fn canon_egcd(a: i64, b: i64, c: i64) -> Option<(i64, i64, i64)> {
     let (d, _, yy) = extended_gcd(a, b);
     if c % d == 0 {
@@ -46,7 +55,7 @@ mod test {
         let base = 31;
 
         let base_inv = mod_pow(base, p - 2, p);
-        let identity = (base * base_inv) % p;
+        let identity = (base * base_inv) % p as i64;
 
         assert_eq!(identity, 1);
     }

src/scanner.rs

@@ -17,6 +17,10 @@ impl<B: io::BufRead> Scanner<B> {
     }
 
     /// Use "turbofish" syntax next::<T>() to select data type of next token.
+    ///
+    /// # Panics
+    ///
+    /// Panics if there's an I/O error or if the token cannot be parsed as T.
     pub fn next<T: ::std::str::FromStr>(&mut self) -> T
     where
         T::Err: ::std::fmt::Debug,

src/string_proc.rs

@@ -8,6 +8,10 @@ pub struct Matcher<'a> {
 
 impl<'a> Matcher<'a> {
     /// Sets fail[i] = length of longest proper prefix-suffix of pattern[0...i].
+    ///
+    /// # Panics
+    ///
+    /// Panics if pattern is empty.
     pub fn new(pattern: &'a [u8]) -> Self {
         let mut fail = Vec::with_capacity(pattern.len());
         fail.push(0);
@@ -51,6 +55,10 @@ impl<'a> Matcher<'a> {
 /// Manacher's algorithm for computing palindrome substrings in linear time.
 /// len[2*i] = odd length of palindrome centred at text[i].
 /// len[2*i+1] = even length of palindrome centred at text[i+0.5].
+///
+/// # Panics
+///
+/// Panics if text is empty.
 pub fn palindromes(text: &[u8]) -> Vec<usize> {
     let mut len = Vec::with_capacity(2 * text.len() - 1);
     len.push(1);