graph_api_lib/walker/steps/
head.rs

1use crate::walker::EdgeWalker;
2use crate::walker::builder::{EdgeWalkerBuilder, VertexWalkerBuilder};
3use crate::walker::steps::Endpoints;
4use include_doc::function_body;
5
6impl<'graph, Mutability, Graph, Walker> EdgeWalkerBuilder<'graph, Mutability, Graph, Walker>
7where
8    Graph: crate::graph::Graph,
9    Walker: EdgeWalker<'graph, Graph = Graph>,
10{
11    /// # Head Step
12    ///
13    /// The `head` step transforms an edge traversal into a vertex traversal by moving to the
14    /// head vertex of each edge. In graph theory, the head is the destination/target vertex that
15    /// the edge point to.
16    ///
17    /// ## Visual Diagram
18    ///
19    /// Before head step (with edges as current elements):
20    /// ```text
21    ///   [A] --- edge1* ---> [B] --- edge2* ---> [C]  
22    ///    ^                                         
23    ///    |                                         
24    ///   edge3*                                       
25    ///    |                                         
26    ///   [D]                                        
27    /// ```
28    ///
29    /// After head step (moved to target vertices of edges):
30    /// ```text
31    ///   [A]* --- edge1 ---> [B]* --- edge2 ---> [C]*
32    ///    ^                                         
33    ///    |                                         
34    ///   edge3                                       
35    ///    |                                         
36    ///   [D]
37    /// ```
38    ///
39    /// ## Parameters
40    ///
41    /// None
42    ///
43    /// ## Return Value
44    ///
45    /// A vertex walker that will traverse the destination/target vertices of the edges from the previous step.
46    ///
47    /// ## Example
48    ///
49    /// ```rust
50    #[doc = function_body!("examples/head.rs", example, [])]
51    /// ```
52    ///
53    /// ## Notes
54    ///
55    /// - The `head` step can only be used after an edge traversal step
56    /// - Transforms the traversal type from EdgeWalker to VertexWalker
57    /// - For directed graphs, head refers to the destination/target vertex
58    /// - For undirected graphs, the distinction between head and tail may depend on implementation
59    /// - Commonly used in conjunction with incoming edges to find vertices that point to certain destinations
60    /// - The head-tail terminology follows standard graph theory convention
61    /// - When working with edges, remember that `head()` gives you "where the edge points to" (destination)
62    pub fn head(self) -> VertexWalkerBuilder<'graph, Mutability, Graph, Endpoints<'graph, Walker>> {
63        self.with_vertex_walker(|walker| Endpoints::new(walker, crate::walker::steps::End::Head))
64    }
65}
graph_api_lib/walker/steps/head.rs

graph_api_lib/walker/steps/
head.rs
