Equality functions now return structured errors

Author: vigna

Cargo.toml

@@ -3,9 +3,9 @@ resolver = "2"
 members = ["algo", "cli", "webgraph"]
 
 [workspace.dependencies]
-webgraph = {path="./webgraph", version="0.3.0"}
-webgraph-algo = {path="./algo", version="0.2.0"}
-webgraph-cli = {path="./cli", version="0.1.0"}
+webgraph = { path = "./webgraph", version = "0.3.0" }
+webgraph-algo = { path = "./algo", version = "0.2.0" }
+webgraph-cli = { path = "./cli", version = "0.1.0" }
 
 card-est-array = "0.1.0"
 epserde = "0.8.0"
@@ -35,13 +35,14 @@ serde = { version = "1.0.217", features = ["serde_derive"] }
 serde_json = "1.0.137"
 zstd = "0.13"
 value-traits = "0.1.3"
+thiserror = "2.0.12"
 
 [profile.release]
-opt-level = 3            # like --release
+opt-level = 3             # like --release
 #lto = "fat"              # Full LTO
-overflow-checks = false  # Disable integer overflow checks.
-debug = true             # Include debug info.
-debug-assertions = false # Enables debug assertions.
+overflow-checks = false   # Disable integer overflow checks.
+debug = true              # Include debug info.
+debug-assertions = false  # Enables debug assertions.
 #codegen-units = 1        # slower compile times, but maybe better perf
 
 [profile.bench]

webgraph/Cargo.toml

@@ -45,6 +45,7 @@ predicates.workspace = true
 java-properties.workspace = true
 sync-cell-slice.workspace = true
 arbitrary = { workspace = true, optional = true }
+thiserror.workspace = true
 
 libc = "0.2.155"
 impl-tools = "0.11.2"

webgraph/src/graphs/csr_graph.rs

@@ -374,9 +374,9 @@ mod test {
         let csr = <CsrGraph>::from_seq_graph(&g);
         labels::check_impl(&csr);
         // We should be able to use eq_sorted
-        graph::eq(&g, &csr);
+        assert!(graph::eq(&g, &csr).is_ok());
 
-        let csr = CompressedCsrGraph::from_graph(&g);
+        let _csr = CompressedCsrGraph::from_graph(&g);
         /*graph::eq(&g, &csr);
         labels::check_impl(&csr);*/
     }

webgraph/src/traits/graph.rs

@@ -43,6 +43,7 @@ use impl_tools::autoimpl;
 use lender::*;
 
 use super::{
+    labels::EqError,
     lenders::{LenderIntoIter, NodeLabelsLender},
     SortedIterator, SortedLender,
 };
@@ -62,13 +63,16 @@ struct this_method_cannot_be_called_use_successors_instead;
 #[autoimpl(for<S: trait + ?Sized> &S, &mut S, Rc<S>)]
 pub trait SequentialGraph: SequentialLabeling<Label = usize> {}
 
-/// Returns true if the two provided graphs with sorted lenders are equal.
+/// Checks if the two provided graphs with sorted lenders are equal.
 ///
 /// This associated function can be used to compare graphs with [sorted
 /// lenders](crate::lenders::SortedLender), but whose iterators [are not
 /// sorted](crate::lenders::SortedIterator). If the graphs are sorted,
 /// [`SequentialLabeling::eq_sorted`] should be used instead.
-pub fn eq<G0: SequentialGraph, G1: SequentialGraph>(g0: &G0, g1: &G1) -> bool
+///
+/// If the two graphs are different, an [`EqError`] is returned describing
+/// the first difference found.
+pub fn eq<G0: SequentialGraph, G1: SequentialGraph>(g0: &G0, g1: &G1) -> Result<(), EqError>
 where
     for<'a> G0::Lender<'a>: SortedLender,
     for<'a> G1::Lender<'a>: SortedLender,
@@ -77,19 +81,20 @@ where
     // but due to current limitations of the borrow checker, we would need to
     // make G0 and G1 'static.
     if g0.num_nodes() != g1.num_nodes() {
-        return false;
+        return Err(EqError::NumNodes {
+            first: g0.num_nodes(),
+            second: g1.num_nodes(),
+        });
     }
     for_!(((node0, succ0), (node1, succ1)) in g0.iter().zip(g1.iter()) {
         debug_assert_eq!(node0, node1);
         let mut succ0 = succ0.into_iter().collect::<Vec<_>>();
         let mut succ1 = succ1.into_iter().collect::<Vec<_>>();
         succ0.sort();
         succ1.sort();
-        if succ0 != succ1 {
-            return false;
-        }
+        super::labels::eq_succs(node0, succ0, succ1)?;
     });
-    true
+    Ok(())
 }
 
 /// Convenience type alias for the iterator over the successors of a node
@@ -155,36 +160,35 @@ pub trait RandomAccessGraph: RandomAccessLabeling<Label = usize> + SequentialGra
 #[autoimpl(for<S: trait + ?Sized> &S, &mut S, Rc<S>)]
 pub trait LabeledSequentialGraph<L>: SequentialLabeling<Label = (usize, L)> {}
 
-/// Returns true if the two provided labeled graphs with sorted lenders are
-/// equal.
+/// Checks if the two provided labeled graphs with sorted lenders are equal.
 ///
 /// This associated function can be used to compare graphs with [sorted
 /// lenders](crate::lenders::SortedLender), but whose iterators [are not
 /// sorted](crate::lenders::SortedIterator). If the graphs are sorted,
 /// [`SequentialLabeling::eq_sorted`] should be used instead.
+///
+/// If the two graphs are different, an [`EqError`] is returned describing
+/// the first difference found.
 pub fn eq_labeled<M, G0: LabeledSequentialGraph<M>, G1: LabeledSequentialGraph<M>>(
     g0: &G0,
     g1: &G1,
-) -> bool
+) -> Result<(), EqError>
 where
     for<'a> G0::Lender<'a>: SortedLender,
     for<'a> G1::Lender<'a>: SortedLender,
-    M: PartialEq,
+    M: PartialEq + std::fmt::Debug,
 {
     if g0.num_nodes() != g1.num_nodes() {
-        return false;
+        return Err(EqError::NumNodes {
+            first: g0.num_nodes(),
+            second: g1.num_nodes(),
+        });
     }
     for_!(((node0, succ0), (node1, succ1)) in g0.iter().zip(g1.iter()) {
         debug_assert_eq!(node0, node1);
-        let mut succ0 = succ0.into_iter().collect::<Vec<_>>();
-        let mut succ1 = succ1.into_iter().collect::<Vec<_>>();
-        succ0.sort_by_key(|x| x.0);
-        succ1.sort_by_key(|x| x.0);
-        if succ0 != succ1 {
-            return false;
-        }
+        super::labels::eq_succs(node0, succ0, succ1)?;
     });
-    true
+    Ok(())
 }
 
 /// A wrapper associating to each successor the label `()`.

webgraph/src/traits/labels.rs

@@ -34,6 +34,7 @@ use impl_tools::autoimpl;
 use lender::*;
 use rayon::ThreadPool;
 use std::rc::Rc;
+use thiserror::Error;
 
 use sux::{traits::Succ, utils::FairChunks};
 
@@ -198,31 +199,105 @@ pub trait SequentialLabeling {
     }
 }
 
-/// Returns true if the two provided sorted labelings are equal.
+/// Error types that can occur during graph equality checking.
+#[derive(Error, Debug, Clone, PartialEq, Eq)]
+pub enum EqError {
+    /// The graphs have different numbers of nodes.
+    #[error("Different number of nodes: {first} != {second}")]
+    NumNodes { first: usize, second: usize },
+
+    /// The graphs have different numbers of arcs.
+    #[error("Different number of arcs: {first} !={second}")]
+    NumArcs { first: u64, second: u64 },
+
+    /// The graphs have different successors for a specific node.
+    #[error("Different successors for node {node}: at index {index} {first} != {second}")]
+    Successors {
+        node: usize,
+        index: usize,
+        first: String,
+        second: String,
+    },
+
+    /// The graphs have different outdegrees for a specific node.
+    #[error("Different outdegree for node {node}: {first} != {second}")]
+    Outdegree {
+        node: usize,
+        first: usize,
+        second: usize,
+    },
+}
+
+#[doc(hidden)]
+/// Checks whether two sorted successors lists are identical,
+/// returning an appropriate error.
+pub fn eq_succs<L: PartialEq + std::fmt::Debug>(
+    node: usize,
+    succ0: impl IntoIterator<Item = L>,
+    succ1: impl IntoIterator<Item = L>,
+) -> Result<(), EqError> {
+    let mut succ0 = succ0.into_iter();
+    let mut succ1 = succ1.into_iter();
+    let mut index = 0;
+    loop {
+        match (succ0.next(), succ1.next()) {
+            (None, None) => return Ok(()),
+            (Some(s0), Some(s1)) => {
+                if s0 != s1 {
+                    return Err(EqError::Successors {
+                        node,
+                        index,
+                        first: format!("{:?}", s0),
+                        second: format!("{:?}", s1),
+                    });
+                }
+            }
+            (None, Some(_)) => {
+                return Err(EqError::Outdegree {
+                    node,
+                    first: index,
+                    second: index + 1 + succ1.count(),
+                });
+            }
+            (Some(_), None) => {
+                return Err(EqError::Outdegree {
+                    node,
+                    first: index + 1 + succ0.count(),
+                    second: index,
+                });
+            }
+        }
+        index += 1;
+    }
+}
+
+/// Checks if the two provided sorted labelings are equal.
 ///
-/// Since graphs are labelings, this function can also be used
-/// to check whether sorted graphs are equal.
+/// Since graphs are labelings, this function can also be used to check whether
+/// sorted graphs are equal. If the graphs are different, an [`EqError`] is
+/// returned describing the first difference found.
 pub fn eq_sorted<L0: SequentialLabeling, L1: SequentialLabeling<Label = L0::Label>>(
     l0: &L0,
     l1: &L1,
-) -> bool
+) -> Result<(), EqError>
 where
     for<'a> L0::Lender<'a>: SortedLender,
     for<'a> L1::Lender<'a>: SortedLender,
     for<'a, 'b> LenderIntoIter<'b, L0::Lender<'a>>: SortedIterator,
     for<'a, 'b> LenderIntoIter<'b, L0::Lender<'a>>: SortedIterator,
-    L0::Label: PartialEq,
+    L0::Label: PartialEq + std::fmt::Debug,
 {
     if l0.num_nodes() != l1.num_nodes() {
-        return false;
+        return Err(EqError::NumNodes {
+            first: l0.num_nodes(),
+            second: l1.num_nodes(),
+        });
     }
     for_!(((node0, succ0), (node1, succ1)) in l0.iter().zip(l1.iter()) {
         debug_assert_eq!(node0, node1);
-        if !succ0.into_iter().eq(succ1.into_iter()) {
-            return false;
-        }
+        eq_succs(node0, succ0, succ1)?;
     });
-    true
+    Ok(())
 }
 
 /// Convenience type alias for the iterator over the labels of a node

webgraph/tests/test_labels_graphs.rs

@@ -9,15 +9,15 @@ use webgraph::graphs::vec_graph::VecGraph;
 use webgraph::prelude::*;
 
 #[test]
-fn test_eq() {
+fn test_eq() -> anyhow::Result<()> {
     let arcs = vec![(0, 1), (0, 2), (1, 2), (1, 3), (2, 4), (3, 4)];
     let g0 = VecGraph::from_arcs(arcs.iter().copied());
     let mut g1 = g0.clone();
-    assert!(labels::eq_sorted(&g0, &g1));
-    assert!(graph::eq(&g0, &g1));
+    labels::eq_sorted(&g0, &g1)?;
+    graph::eq(&g0, &g1)?;
     g1.add_arc(0, 3);
-    assert!(!labels::eq_sorted(&g0, &g1));
-    assert!(!graph::eq(&g0, &g1));
+    assert!(labels::eq_sorted(&g0, &g1).is_err());
+    assert!(graph::eq(&g0, &g1).is_err());
 
     let arcs = vec![
         (0, 1, 0),
@@ -29,9 +29,60 @@ fn test_eq() {
     ];
     let g0 = LabeledVecGraph::<usize>::from_arcs(arcs.iter().copied());
     let mut g1 = g0.clone();
-    assert!(labels::eq_sorted(&g0, &g1));
-    assert!(graph::eq_labeled(&g0, &g1));
+    labels::eq_sorted(&g0, &g1)?;
+    graph::eq_labeled(&g0, &g1)?;
     g1.add_arc(0, 3, 6);
-    assert!(!labels::eq_sorted(&g0, &g1));
-    assert!(!graph::eq_labeled(&g0, &g1));
+    assert!(labels::eq_sorted(&g0, &g1).is_err());
+    assert!(graph::eq_labeled(&g0, &g1).is_err());
+    Ok(())
+}
+
+#[test]
+fn test_graph_eq_error() -> anyhow::Result<()> {
+    // Test eq function with different successors
+    let arcs1 = vec![(0, 0), (0, 2), (1, 2)];
+    let arcs2 = vec![(0, 0), (0, 1), (1, 2)]; // Different successor for node 0
+    let g1 = VecGraph::from_arcs(arcs1.iter().copied());
+    let mut g2 = VecGraph::from_arcs(arcs2.iter().copied());
+
+    let result = graph::eq(&g1, &g2);
+    if let Err(EqError::Successors { node, index, .. }) = result {
+        assert_eq!(node, 0);
+        assert_eq!(index, 1);
+    } else {
+        panic!("Expected Successors error, got: {:?}", result);
+    }
+
+    g2.add_node(3);
+    let result = graph::eq(&g1, &g2);
+    if let Err(EqError::NumNodes {
+        first: 3,
+        second: 4,
+    }) = result
+    {
+    } else {
+        panic!("Expected NumNodes error, got: {:?}", result);
+    }
+
+    // Test eq_labeled function with different labels
+    let labeled_arcs1 = vec![(0, 1, "a"), (0, 2, "b"), (1, 2, "c")];
+    let labeled_arcs2 = vec![(0, 1, "a"), (0, 2, "x"), (1, 2, "c")]; // Different label for arc (0,2)
+    let lg1 = LabeledVecGraph::from_arcs(labeled_arcs1.iter().copied());
+    let lg2 = LabeledVecGraph::from_arcs(labeled_arcs2.iter().copied());
+
+    let result = graph::eq_labeled(&lg1, &lg2);
+    assert!(result.is_err());
+
+    if let Err(EqError::Successors { node, index, .. }) = result {
+        assert_eq!(node, 0);
+        assert_eq!(index, 1);
+    } else {
+        panic!("Expected Successors error, got: {:?}", result);
+    }
+
+    // Test successful equality
+    graph::eq(&g1, &g1)?;
+
+    graph::eq_labeled(&lg1, &lg1)?;
+    Ok(())
 }

webgraph/tests/test_par_bvcomp.rs

@@ -11,7 +11,6 @@ use std::path::PathBuf;
 use anyhow::Result;
 use dsi_bitstream::prelude::*;
 use dsi_progress_logger::prelude::*;
-use lender::*;
 use log::info;
 use webgraph::prelude::*;
 
@@ -75,7 +74,7 @@ fn _test_par_bvcomp(basename: &str) -> Result<()> {
                 .load()?;
 
         info!("Checking that the newly compressed graph is equivalent to the original one...");
-        assert!(graph::eq(&graph, &comp_graph));
+        graph::eq(&graph, &comp_graph)?;
 
         let offsets_path = tmp_basename.with_extension(OFFSETS_EXTENSION);
         let mut offsets_reader =