docs: add graph examples and benchmarks

Author: jeresoftx

Cargo.toml

@@ -97,6 +97,18 @@ path = "examples/soluciones/trie_autocomplete.rs"
 name = "solution_trie_unicode_policy"
 path = "examples/soluciones/trie_unicode_policy.rs"
 
+[[example]]
+name = "solution_graph_dependency_edges"
+path = "examples/soluciones/graph_dependency_edges.rs"
+
+[[example]]
+name = "solution_graph_social_neighbors"
+path = "examples/soluciones/graph_social_neighbors.rs"
+
+[[example]]
+name = "solution_graph_route_matrix"
+path = "examples/soluciones/graph_route_matrix.rs"
+
 [[bench]]
 name = "vector_bench"
 path = "benches/vector_bench.rs"
@@ -131,3 +143,8 @@ harness = false
 name = "trie_bench"
 path = "benches/trie_bench.rs"
 harness = false
+
+[[bench]]
+name = "graph_bench"
+path = "benches/graph_bench.rs"
+harness = false

benches/graph_bench.rs

@@ -0,0 +1,99 @@
+use rust_data_structures::graph::{AdjacencyMatrix, Graph};
+use std::hint::black_box;
+use std::time::{Duration, Instant};
+
+const SIZE: i32 = 700;
+
+fn main() {
+    println!("graph benchmark (manual, std::time::Instant)");
+    println!("size: {SIZE}");
+    println!(
+        "adjacency list sparse build: {:?}",
+        bench_list_sparse_build()
+    );
+    println!(
+        "adjacency matrix sparse build: {:?}",
+        bench_matrix_sparse_build()
+    );
+    println!("adjacency list edge query: {:?}", bench_list_edge_query());
+    println!(
+        "adjacency matrix edge query: {:?}",
+        bench_matrix_edge_query()
+    );
+    println!(
+        "adjacency list neighbor scan: {:?}",
+        bench_list_neighbor_scan()
+    );
+}
+
+fn bench_list_sparse_build() -> Duration {
+    let start = Instant::now();
+    black_box(build_list());
+    start.elapsed()
+}
+
+fn bench_matrix_sparse_build() -> Duration {
+    let start = Instant::now();
+    black_box(build_matrix());
+    start.elapsed()
+}
+
+fn bench_list_edge_query() -> Duration {
+    let graph = build_list();
+
+    let start = Instant::now();
+    for node in 0..SIZE {
+        black_box(graph.has_edge(node, (node + 1) % SIZE));
+    }
+    start.elapsed()
+}
+
+fn bench_matrix_edge_query() -> Duration {
+    let graph = build_matrix();
+
+    let start = Instant::now();
+    for node in 0..SIZE {
+        black_box(graph.has_edge(node, (node + 1) % SIZE));
+    }
+    start.elapsed()
+}
+
+fn bench_list_neighbor_scan() -> Duration {
+    let graph = build_list();
+
+    let start = Instant::now();
+    for node in 0..SIZE {
+        black_box(graph.neighbors(node));
+    }
+    start.elapsed()
+}
+
+fn build_list() -> Graph<i32> {
+    let mut graph = Graph::new_directed();
+
+    for node in 0..SIZE {
+        graph.add_node(node);
+    }
+
+    for node in 0..SIZE {
+        graph.add_edge(node, (node + 1) % SIZE, 1).unwrap();
+        graph.add_edge(node, (node + 7) % SIZE, 1).unwrap();
+    }
+
+    graph
+}
+
+fn build_matrix() -> AdjacencyMatrix<i32> {
+    let mut graph = AdjacencyMatrix::new_directed();
+
+    for node in 0..SIZE {
+        graph.add_node(node);
+    }
+
+    for node in 0..SIZE {
+        graph.add_edge(node, (node + 1) % SIZE, 1).unwrap();
+        graph.add_edge(node, (node + 7) % SIZE, 1).unwrap();
+    }
+
+    graph
+}

diagrams/08-graph.mmd

@@ -0,0 +1,42 @@
+flowchart TB
+    title["Graph: representaciones y operaciones"]
+
+    subgraph logical["Modelo logico"]
+        a["Nodo A"]
+        b["Nodo B"]
+        c["Nodo C"]
+        a -- "peso 7" --> b
+        b -- "peso 2" --> c
+        c -- "peso 4" --> a
+    end
+
+    subgraph list["Lista de adyacencia"]
+        la["A: [(B, 7)]"]
+        lb["B: [(C, 2)]"]
+        lc["C: [(A, 4)]"]
+    end
+
+    subgraph matrix["Matriz de adyacencia"]
+        m1["A,B = 7"]
+        m2["B,C = 2"]
+        m3["C,A = 4"]
+        m4["celdas vacias = sin arista"]
+    end
+
+    subgraph edge_list["Lista de aristas"]
+        e1["(A, B, 7)"]
+        e2["(B, C, 2)"]
+        e3["(C, A, 4)"]
+    end
+
+    logical --> list
+    logical --> matrix
+    logical --> edge_list
+
+    choose_sparse["Grafo disperso<br/>pocas aristas por nodo"]
+    choose_dense["Grafo denso<br/>muchas consultas de existencia"]
+    choose_export["Serializacion o auditoria<br/>recorrer aristas"]
+
+    choose_sparse --> list
+    choose_dense --> matrix
+    choose_export --> edge_list

examples/graph_advanced.rs

@@ -0,0 +1,29 @@
+use rust_data_structures::graph::{AdjacencyMatrix, Graph};
+
+fn main() {
+    let nodes = ["a", "b", "c", "d"];
+    let routes = [
+        ("a", "b", 10),
+        ("a", "c", 15),
+        ("b", "c", 3),
+        ("c", "d", 7),
+        ("d", "a", 20),
+    ];
+
+    let mut list = Graph::new_directed();
+    let mut matrix = AdjacencyMatrix::new_directed();
+
+    for node in nodes {
+        list.add_node(node);
+        matrix.add_node(node);
+    }
+
+    for (from, to, weight) in routes {
+        list.add_edge(from, to, weight).unwrap();
+        matrix.add_edge(from, to, weight).unwrap();
+    }
+
+    println!("lista: vecinos de a = {:?}", list.neighbors("a").unwrap());
+    println!("matriz: peso a->c = {:?}", matrix.edge_weight("a", "c"));
+    println!("matriz: existe b->d = {}", matrix.has_edge("b", "d"));
+}

examples/graph_basic.rs

@@ -0,0 +1,23 @@
+use rust_data_structures::graph::Graph;
+
+fn main() {
+    let mut dependencies = Graph::new_directed();
+
+    dependencies.add_node("lexer");
+    dependencies.add_node("parser");
+    dependencies.add_node("type-checker");
+
+    dependencies.add_edge("parser", "lexer", 1).unwrap();
+    dependencies.add_edge("type-checker", "parser", 1).unwrap();
+
+    println!("nodos: {}", dependencies.node_count());
+    println!("aristas: {}", dependencies.edge_count());
+    println!(
+        "parser depende de lexer: {}",
+        dependencies.has_edge("parser", "lexer")
+    );
+    println!(
+        "lexer depende de parser: {}",
+        dependencies.has_edge("lexer", "parser")
+    );
+}

examples/graph_intermediate.rs

@@ -0,0 +1,17 @@
+use rust_data_structures::graph::Graph;
+
+fn main() {
+    let mut social = Graph::new_undirected();
+
+    for person in ["ana", "beatriz", "carlos", "diego"] {
+        social.add_node(person);
+    }
+
+    social.add_edge("ana", "beatriz", 5).unwrap();
+    social.add_edge("ana", "carlos", 2).unwrap();
+    social.add_edge("beatriz", "diego", 1).unwrap();
+
+    println!("amistades logicas: {}", social.edge_count());
+    println!("vecinos de ana: {:?}", social.neighbors("ana").unwrap());
+    println!("beatriz ve a ana: {}", social.has_edge("beatriz", "ana"));
+}

examples/graph_real_case.rs

@@ -0,0 +1,30 @@
+use rust_data_structures::graph::Graph;
+
+fn main() {
+    let mut course_map = Graph::new_directed();
+
+    for course in [
+        "rust-basics",
+        "ownership",
+        "data-structures",
+        "algorithms",
+        "distributed-systems",
+    ] {
+        course_map.add_node(course);
+    }
+
+    course_map.add_edge("ownership", "rust-basics", 1).unwrap();
+    course_map
+        .add_edge("data-structures", "ownership", 1)
+        .unwrap();
+    course_map
+        .add_edge("algorithms", "data-structures", 1)
+        .unwrap();
+    course_map
+        .add_edge("distributed-systems", "algorithms", 1)
+        .unwrap();
+
+    for edge in course_map.edges() {
+        println!("{} requiere {}", edge.from, edge.to);
+    }
+}

examples/soluciones/graph_dependency_edges.rs

@@ -0,0 +1,23 @@
+use rust_data_structures::graph::Graph;
+
+fn main() {
+    let mut graph = Graph::new_directed();
+
+    for crate_name in ["api", "domain", "database", "observability"] {
+        graph.add_node(crate_name);
+    }
+
+    graph.add_edge("api", "domain", 1).unwrap();
+    graph.add_edge("api", "observability", 1).unwrap();
+    graph.add_edge("database", "domain", 1).unwrap();
+
+    let edges = graph.edges();
+
+    assert_eq!(edges.len(), 3);
+    assert!(graph.has_edge("api", "domain"));
+    assert!(!graph.has_edge("domain", "api"));
+
+    for edge in edges {
+        println!("{} -> {}", edge.from, edge.to);
+    }
+}

examples/soluciones/graph_route_matrix.rs

@@ -0,0 +1,18 @@
+use rust_data_structures::graph::AdjacencyMatrix;
+
+fn main() {
+    let mut routes = AdjacencyMatrix::new_directed();
+
+    for city in ["mxn", "gdl", "qro"] {
+        routes.add_node(city);
+    }
+
+    routes.add_edge("mxn", "gdl", 9).unwrap();
+    routes.add_edge("gdl", "qro", 5).unwrap();
+
+    assert_eq!(routes.edge_weight("mxn", "gdl"), Some(9));
+    assert!(!routes.has_edge("qro", "mxn"));
+    assert_eq!(routes.node_count(), 3);
+
+    println!("mxn -> gdl: {:?}", routes.edge_weight("mxn", "gdl"));
+}

examples/soluciones/graph_social_neighbors.rs

@@ -0,0 +1,21 @@
+use rust_data_structures::graph::Graph;
+
+fn main() {
+    let mut graph = Graph::new_undirected();
+
+    for person in ["ana", "beatriz", "carlos", "diego"] {
+        graph.add_node(person);
+    }
+
+    graph.add_edge("ana", "beatriz", 10).unwrap();
+    graph.add_edge("ana", "carlos", 4).unwrap();
+    graph.add_edge("diego", "beatriz", 2).unwrap();
+
+    let ana_neighbors = graph.neighbors("ana").unwrap();
+
+    assert_eq!(ana_neighbors, vec![("beatriz", 10), ("carlos", 4)]);
+    assert!(graph.has_edge("beatriz", "ana"));
+    assert_eq!(graph.edge_count(), 3);
+
+    println!("vecinos de ana: {ana_neighbors:?}");
+}