graph_api_lib/walker/steps/
collect.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    /// # Collect Step
11    ///
12    /// The `collect` step finalizes a traversal and gathers the results into a collection.
13    /// This is a terminal operation that ends the traversal and provides access to the traversed elements.
14    ///
15    /// ## Visual Diagram
16    ///
17    /// Before collect step (with elements in traversal):
18    /// ```text
19    ///   [A]* --- edge1 ---> [B]* --- edge2 ---> [C]*
20    ///    ^
21    ///    |
22    ///   edge3
23    ///    |
24    ///   [D]*
25    /// ```
26    ///
27    /// After collect step (all elements consumed and collected):
28    /// ```text
29    ///   [A] --- edge1 ---> [B] --- edge2 ---> [C]
30    ///    ^
31    ///    |
32    ///   edge3
33    ///    |
34    ///   [D]
35    ///
36    ///   Collection: [A, B, C, D]
37    /// ```
38    ///
39    /// ## Parameters
40    ///
41    /// None - but the resulting collection type is determined by the type parameter provided to the collect call.
42    ///
43    /// ## Return Value
44    ///
45    /// Returns a collection of the traversed elements. The exact type depends on what you're collecting into, commonly:
46    /// - `Vec<ElementId>` for simple ID collection
47    /// - `Vec<(ElementId, Context)>` when context is used
48    /// - Custom types when implementing `FromIterator`
49    ///
50    /// ## Example
51    ///
52    /// ```rust
53    #[doc = function_body!("examples/collect.rs", example, [])]
54    /// ```
55    ///
56    /// For more examples, see the [collect example](https://github.com/yourusername/graph-api/blob/main/graph-api-lib/examples/collect.rs).
57    ///
58    /// ## Notes
59    ///
60    /// - The `collect` step is a terminal operation - no further traversal steps can be added after it
61    /// - When collecting with context, use `map` first to format the data for collection
62    /// - The collect step fully consumes the traversal
63    /// - Most commonly used with `Vec<_>`, but can collect into any type that implements `FromIterator`
64    /// - Consider using `limit` before `collect` for large graphs to avoid excessive memory use
65    /// - For single-element queries, consider using `first()` instead of `collect` for efficiency
66    pub fn collect<T: FromIterator<Graph::VertexId>>(self) -> T
67    where
68        Walker: VertexWalker<'graph>,
69    {
70        self.into_iter().collect()
71    }
72}
73
74impl<'graph, Mutability, Graph, Walker> EdgeWalkerBuilder<'graph, Mutability, Graph, Walker>
75where
76    Graph: crate::graph::Graph,
77    Walker: EdgeWalker<'graph, Graph = Graph>,
78{
79    /// Collects all edge IDs from this traversal into a collection of type `T`.
80    ///
81    /// This is a terminal operation that consumes the traversal.
82    ///
83    /// See the documentation for [`VertexWalkerBuilder::collect`] for more details.
84    pub fn collect<T: FromIterator<Graph::EdgeId>>(self) -> T
85    where
86        Walker: EdgeWalker<'graph>,
87    {
88        self.into_iter().collect()
89    }
90}
graph_api_lib/walker/steps/collect.rs

graph_api_lib/walker/steps/
collect.rs
