graph_api_lib/walker/steps/
first.rs

1use crate::walker::builder::{EdgeWalkerBuilder, VertexWalkerBuilder};
2use crate::walker::{EdgeWalker, VertexWalker};
3use include_doc::function_body;
4
5impl<'graph, Mutability, Graph, Walker> VertexWalkerBuilder<'graph, Mutability, Graph, Walker>
6where
7    Graph: crate::graph::Graph,
8    Walker: VertexWalker<'graph, Graph = Graph>,
9{
10    /// # First Step
11    ///
12    /// The `first` step retrieves only the first vertex from a traversal and terminates.
13    /// This is a terminal operation that consumes the walker and returns an Option containing
14    /// the first vertex ID if one exists, or None if the traversal is empty.
15    ///
16    /// ## Visual Diagram
17    ///
18    /// Before first step (multiple vertices in traversal):
19    /// ```text
20    ///   [Project A]* --- uses ---> [Project B]* --- created_by ---> [Person]*
21    ///    ^
22    ///    |
23    ///   uses
24    ///    |
25    ///   [Project C]*
26    /// ```
27    ///
28    /// After first step (only first vertex returned):
29    /// ```text
30    ///   [Project A]* --- uses ---> [Project B] --- created_by ---> [Person]
31    ///    ^
32    ///    |
33    ///   uses
34    ///    |
35    ///   [Project C]
36    ///
37    ///   Result: Project A
38    /// ```
39    ///
40    /// ## Parameters
41    ///
42    /// None
43    ///
44    /// ## Return Value
45    ///
46    /// `Option<VertexId>` - Returns Some(id) with the first vertex ID if the traversal contains at least one element,
47    /// or None if the traversal is empty.
48    ///
49    /// ## Example
50    ///
51    /// ```rust
52    #[doc = function_body!("examples/first.rs", vertex_example, [])]
53    /// ```
54    ///
55    /// ## Notes
56    ///
57    /// - The `first` step is a terminal operation - it consumes the walker and returns immediately
58    /// - If the traversal is empty, `first` returns None
59    /// - More efficient than using `collect` when you only need the first vertex
60    /// - Can be combined with filtering to find the first vertex of a specific type
61    /// - Order depends on the traversal steps and graph implementation
62    /// - For more deterministic results, consider using range indexes or sorting steps
63    pub fn first(mut self) -> Option<Graph::VertexId>
64    where
65        'graph: 'graph,
66    {
67        let graph = self.graph();
68        let mut walker = self.walker();
69        walker.next(graph)
70    }
71}
72
73impl<'graph, Mutability, Graph, Walker> EdgeWalkerBuilder<'graph, Mutability, Graph, Walker>
74where
75    Graph: crate::graph::Graph,
76    Walker: EdgeWalker<'graph, Graph = Graph>,
77{
78    /// # First Step
79    ///
80    /// The `first` step retrieves only the first edge from a traversal and terminates.
81    /// This is a terminal operation that consumes the walker and returns an Option containing
82    /// the first edge ID if one exists, or None if the traversal is empty.
83    ///
84    /// ## Visual Diagram
85    ///
86    /// Before first step (multiple edges in traversal):
87    /// ```text
88    ///   [Person A] --- knows* ---> [Person B] --- created* ---> [Project]
89    ///    ^                                         
90    ///    |                                         
91    ///   owns*                                       
92    ///    |                                         
93    ///   [Company]                                        
94    /// ```
95    ///
96    /// After first step (only first edge returned):
97    /// ```text
98    ///   [Person A] --- knows* ---> [Person B] --- created ---> [Project]
99    ///    ^                                         
100    ///    |                                         
101    ///   owns                                       
102    ///    |                                         
103    ///   [Company]               
104    ///
105    ///   Result: knows
106    /// ```
107    ///
108    /// ## Parameters
109    ///
110    /// None
111    ///
112    /// ## Return Value
113    ///
114    /// `Option<EdgeId>` - Returns Some(id) with the first edge ID if the traversal contains at least one edge,
115    /// or None if the traversal is empty.
116    ///
117    /// ## Example
118    ///
119    /// ```rust
120    #[doc = function_body!("examples/first.rs", edge_example, [])]
121    /// ```
122    ///
123    /// ## Notes
124    ///
125    /// - Efficient for finding the first matching edge in a graph
126    /// - Particularly useful for checking existence of specific relationship types
127    /// - Often used with filtering to find specific types of edges
128    /// - Returns immediately after finding the first edge, improving performance for large graphs
129    /// - After getting the edge ID, you can use graph.edge() to access the full edge data
130    pub fn first(mut self) -> Option<Graph::EdgeId> {
131        let graph = self.graph();
132        let mut walker = self.walker();
133        walker.next(graph)
134    }
135}
graph_api_lib/walker/steps/first.rs

graph_api_lib/walker/steps/
first.rs
