gotgraph 0.2.0

A type-safe, scope-aware graph library that leverages Rust's type system to prevent common graph-related bugs at compile time
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

#![doc = include_str!("../README.md")]

/// Graph algorithms module containing strongly connected components and other graph algorithms.
pub mod algo;
/// Core graph traits and context-based operations.
pub mod graph;
/// Vector-based graph implementation.
pub mod vec_graph;

/// Commonly used types and traits for easy importing.
///
/// This module re-exports the most frequently used items from the library,
/// allowing users to import everything they need with a single use statement.
///
/// # Example
///
/// ```rust
/// use gotgraph::prelude::*;
///
/// let mut graph: VecGraph<i32, &str> = VecGraph::default();
/// // Now you have access to Graph, GraphUpdate, etc.
/// ```
pub mod prelude {
    pub use crate::graph::{Graph, GraphRemove, GraphRemoveEdge, GraphUpdate};
    pub use crate::vec_graph::VecGraph;
}

/// A trait for associative containers that map keys to values.
///
/// This trait provides a common interface for data structures that associate
/// keys with values, similar to hash maps or arrays. It's used extensively
/// throughout the library for creating mappings from node/edge indices to
/// computed values.
///
/// # Type Parameters
///
/// - `K`: The key type (typically node or edge indices)
/// - `V`: The value type
///
/// # Examples
///
/// ```rust
/// use gotgraph::prelude::*;
///
/// let mut graph: VecGraph<i32, &str> = VecGraph::default();
/// graph.scope_mut(|mut ctx| {
///     ctx.add_node(10);
///     ctx.add_node(20);
/// });
///
/// graph.scope(|ctx| {
///     // Create a mapping that doubles each node's value
///     let doubled = ctx.init_node_map(|_tag, &value| value * 2);
///     
///     for node_tag in ctx.node_indices() {
///         println!("Doubled: {}", doubled[node_tag]);
///     }
/// });
/// ```
pub trait Mapping<K, V>: std::ops::IndexMut<K, Output = V> + IntoIterator<Item = V> {
    /// Transform this mapping by applying a function to each value.
    ///
    /// Creates a new mapping with the same keys but transformed values.
    ///
    /// # Parameters
    ///
    /// - `f`: A function that transforms each value from type `V` to type `VV`
    ///
    /// # Returns
    ///
    /// A new mapping with transformed values.
    fn map<VV>(self, f: impl FnMut(V) -> VV) -> impl Mapping<K, VV>;

    /// Returns an iterator over references to the values in this mapping.
    ///
    /// The order of iteration is implementation-defined.
    fn iter<'a>(&'a self) -> impl Iterator<Item = &'a V>
    where
        V: 'a;

    /// Returns an iterator over mutable references to the values in this mapping.
    ///
    /// The order of iteration is implementation-defined.
    fn iter_mut<'a>(&'a mut self) -> impl Iterator<Item = &'a mut V>
    where
        V: 'a;

    /// Gets a reference to the value associated with the given key without bounds checking.
    ///
    /// # Safety
    ///
    /// The caller must ensure that the key exists in the mapping. Calling this method
    /// with a non-existent key results in undefined behavior.
    ///
    /// # Parameters
    ///
    /// - `key`: The key to look up
    ///
    /// # Returns
    ///
    /// A reference to the value associated with the key.
    unsafe fn get_unchecked(&self, key: K) -> &V;

    /// Gets a mutable reference to the value associated with the given key without bounds checking.
    ///
    /// # Safety
    ///
    /// The caller must ensure that the key exists in the mapping. Calling this method
    /// with a non-existent key results in undefined behavior.
    ///
    /// # Parameters
    ///
    /// - `key`: The key to look up
    ///
    /// # Returns
    ///
    /// A mutable reference to the value associated with the key.
    unsafe fn get_unchecked_mut(&mut self, key: K) -> &mut V;
}

type Invariant<'a> = core::marker::PhantomData<fn(&'a ()) -> &'a ()>;