graph_api_lib/walker/steps/
vertices_by_id.rs

1use crate::ElementId;
2use crate::graph::Graph;
3use crate::walker::builder::{StartWalkerBuilder, VertexWalkerBuilder};
4use crate::walker::steps::Empty;
5use crate::walker::{VertexWalker, Walker};
6use include_doc::function_body;
7use std::marker::PhantomData;
8// ================ VERTEX_ITER IMPLEMENTATION ================
9
10pub struct VertexIter<'graph, Parent, Iter>
11where
12    Parent: VertexWalker<'graph>,
13    Iter: Iterator<Item = <Parent::Graph as Graph>::VertexId>,
14{
15    _phantom_data: PhantomData<&'graph ()>,
16    parent: Parent,
17    start: Iter,
18}
19
20impl<'graph, Parent, Iter> VertexIter<'graph, Parent, Iter>
21where
22    Parent: VertexWalker<'graph>,
23    Iter: Iterator<Item = <Parent::Graph as Graph>::VertexId>,
24{
25    pub fn new(parent: Parent, start: Iter) -> Self {
26        Self {
27            _phantom_data: Default::default(),
28            parent,
29            start,
30        }
31    }
32}
33
34impl<'graph, Parent, Iter> Walker<'graph> for VertexIter<'graph, Parent, Iter>
35where
36    Parent: VertexWalker<'graph>,
37    Iter: Iterator<Item = <Parent::Graph as Graph>::VertexId>,
38{
39    type Graph = Parent::Graph;
40
41    type Context = Parent::Context;
42    fn next_element(&mut self, graph: &'graph Self::Graph) -> Option<ElementId<Self::Graph>> {
43        self.next(graph).map(ElementId::Vertex)
44    }
45    fn ctx(&self) -> &Parent::Context {
46        self.parent.ctx()
47    }
48    fn ctx_mut(&mut self) -> &mut Self::Context {
49        self.parent.ctx_mut()
50    }
51}
52
53impl<'graph, Parent, Iter> VertexWalker<'graph> for VertexIter<'graph, Parent, Iter>
54where
55    Parent: VertexWalker<'graph>,
56    Iter: Iterator<Item = <Parent::Graph as Graph>::VertexId>,
57{
58    fn next(&mut self, _graph: &Self::Graph) -> Option<<Self::Graph as Graph>::VertexId> {
59        self.start.next()
60    }
61}
62
63impl<'graph, Mutability, Graph, Walker> VertexWalkerBuilder<'graph, Mutability, Graph, Walker>
64where
65    Graph: crate::graph::Graph,
66    Walker: VertexWalker<'graph, Graph = Graph>,
67{
68    /// # Vertices By ID Step
69    ///
70    /// The `vertices_by_id` step allows you to begin a traversal from a specific set of vertex IDs.
71    /// This is useful when you already know the IDs of the vertices you want to include in your traversal.
72    ///
73    /// ## Visual Diagram
74    ///
75    /// Before vertices_by_id step (empty traversal):
76    /// ```text
77    ///   [A] --- edge1 ---> [B] --- edge2 ---> [C]  
78    ///    ^                                         
79    ///    |                                         
80    ///   edge3                                       
81    ///    |                                         
82    ///   [D]                                        
83    /// ```
84    ///
85    /// After vertices_by_id step (with [id_A, id_C]):
86    /// ```text
87    ///   [A]* --- edge1 ---> [B] --- edge2 ---> [C]*  
88    ///    ^                                         
89    ///    |                                         
90    ///   edge3                                       
91    ///    |                                         
92    ///   [D]                                        
93    /// ```
94    ///
95    /// ## Parameters
96    ///
97    /// - `vertex_ids`: An iterator that yields vertex IDs to include in the traversal
98    ///
99    /// ## Return Value
100    ///
101    /// Returns a traversal containing all vertices with the specified IDs.
102    ///
103    /// ## Example
104    ///
105    /// ```rust
106    #[doc = function_body!("examples/vertices_by_id.rs", example, [])]
107    /// ```
108    ///
109    /// For more examples, see the [vertices_by_id example](https://github.com/yourusername/graph-api/blob/main/graph-api-lib/examples/vertices_by_id.rs).
110    ///
111    /// ## Notes
112    ///
113    /// - This step is efficient when you already know the exact IDs of vertices you want to work with
114    /// - The order of vertices in the traversal will match the order of IDs in the input iterator
115    /// - For vertices that don't exist in the graph, they will be skipped without error
116    /// - This step is often used after a previous traversal has produced vertex IDs of interest
117    /// - When working with a large number of IDs, consider using a `HashSet` for deduplication if needed
118    pub fn vertices_by_id<Iter>(
119        self,
120        vertex_ids: Iter,
121    ) -> VertexWalkerBuilder<'graph, Mutability, Graph, VertexIter<'graph, Walker, Iter::IntoIter>>
122    where
123        Iter: IntoIterator<Item = Graph::VertexId>,
124    {
125        self.with_vertex_walker(|walker| walker.vertices_by_id(vertex_ids))
126    }
127}
128
129impl<'graph, Graph, Mutability, Context> StartWalkerBuilder<'graph, Mutability, Graph, Context>
130where
131    Graph: crate::graph::Graph,
132    Context: Clone + 'static,
133{
134    pub fn vertices_by_id<Iter>(
135        self,
136        vertex_ids: Iter,
137    ) -> VertexWalkerBuilder<
138        'graph,
139        Mutability,
140        Graph,
141        VertexIter<'graph, Empty<Graph, Context>, Iter::IntoIter>,
142    >
143    where
144        Iter: IntoIterator<Item = Graph::VertexId>,
145    {
146        crate::walker::builder::new(self.graph, self.empty.vertices_by_id(vertex_ids))
147    }
148}
graph_api_lib/walker/steps/vertices_by_id.rs

graph_api_lib/walker/steps/
vertices_by_id.rs
