graph_api_lib/walker/steps/
tail.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    /// # Tail Step
12    ///
13    /// The `tail` step transforms an edge traversal into a vertex traversal by moving to the
14    /// tail vertex of each edge. In graph theory, the tail is the source/origin vertex
15    /// that the edge comes from.
16    ///
17    /// ## Visual Diagram
18    ///
19    /// Before tail 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 tail step (moved to source 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 source vertices of the edges from the previous step.
46    ///
47    /// ## Example
48    ///
49    /// ```rust
50    #[doc = function_body!("examples/tail.rs", example, [])]
51    /// ```
52    ///
53    /// For more examples, see the [tail example](https://github.com/yourusername/graph-api/blob/main/graph-api-lib/examples/tail.rs).
54    ///
55    /// ## Notes
56    ///
57    /// - The `tail` step can only be used after an edge traversal step
58    /// - Transforms the traversal type from EdgeWalker to VertexWalker
59    /// - For directed graphs, tail refers to the source/origin vertex
60    /// - For undirected graphs, the distinction between head and tail may depend on implementation
61    /// - Commonly used in conjunction with `edges` to follow relationships
62    /// - The head-tail terminology follows standard graph theory convention
63    /// - When working with edges, remember that `tail()` gives you "where the edge comes from" (source)
64    pub fn tail(self) -> VertexWalkerBuilder<'graph, Mutability, Graph, Endpoints<'graph, Walker>> {
65        self.with_vertex_walker(|walker| Endpoints::new(walker, crate::walker::steps::End::Tail))
66    }
67}
graph_api_lib/walker/steps/tail.rs

graph_api_lib/walker/steps/
tail.rs
