1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
use crate::walker::builder::{EdgeWalkerBuilder, VertexWalkerBuilder};
use crate::walker::steps::into_iter::{EdgeReferenceIterImpl, VertexReferenceIterImpl};
use crate::walker::{EdgeWalker, VertexWalker};
use include_doc::function_body;
impl<'graph, Mutability, Graph, Walker> VertexWalkerBuilder<'graph, Mutability, Graph, Walker>
where
Graph: crate::graph::Graph,
Walker: VertexWalker<'graph, Graph = Graph>,
{
/// # Map Step
///
/// The `map` step transforms vertices in the traversal by applying a mapping function to each vertex.
/// Unlike other steps that continue the traversal chain, `map` returns an iterator that yields the
/// transformed elements directly.
///
/// ## Visual Diagram
///
/// Before map step:
/// ```text
/// [Project A]* --- created_by ---> [Person B]* --- owns ---> [Project C]*
/// ^
/// |
/// uses
/// |
/// [Project D]*
/// ```
///
/// After map step with `vertex -> extract project name`:
/// ```text
/// "Project A", "Person B", "Project C", "Project D"
/// ```
///
/// ## Parameters
///
/// - `mapping`: A function that takes a vertex reference and context, and returns a transformed value.
/// The function signature is `FnMut(Graph::VertexReference<'graph>, Walker::Context) -> R`.
///
/// ## Return Value
///
/// Returns an iterator that yields the transformed elements. The type of the iterator items
/// is determined by the return type of the mapping function.
///
/// ## Example
///
/// ```rust
#[doc = function_body!("examples/map.rs", vertex_example, [])]
/// ```
///
/// ## Notes
///
/// - The `map` step is terminal - it returns an iterator, not a traversal builder
/// - The mapping function has access to both the vertex and its context
/// - After mapping, you can continue with standard Rust iterator operations like filter or collect
/// - Common uses include extracting properties from vertices (e.g., names, IDs, attributes)
/// - For building complex data structures, consider using pattern matching in the mapping function
/// - To map vertices with context data, use `push_context` before mapping
pub fn map<R, M>(mut self, mut mapping: M) -> impl Iterator<Item = R> + 'graph
where
M: FnMut(Graph::VertexReference<'graph>, Walker::Context) -> R + 'graph,
Walker: 'graph,
{
VertexReferenceIterImpl::new(self.graph(), self.walker())
.map(move |(reference, ctx)| mapping(reference, ctx))
}
}
impl<'graph, Mutability, Graph, Walker> EdgeWalkerBuilder<'graph, Mutability, Graph, Walker>
where
Graph: crate::graph::Graph,
Walker: EdgeWalker<'graph, Graph = Graph>,
{
/// # Map Step
///
/// The `map` step transforms edges in the traversal by applying a mapping function to each edge.
/// It returns an iterator that yields the transformed elements, allowing you to convert edge data
/// into any desired format.
///
/// ## Visual Diagram
///
/// Before map step (with edges in traversal):
/// ```text
/// [Person A] --- knows(2018)* ---> [Person B] --- created(2022)* ---> [Project]
/// ^
/// |
/// owns(2020)*
/// |
/// [Company]
/// ```
///
/// After map step with `edge -> relationship description`:
/// ```text
/// "knows since 2018", "created in 2022", "owns since 2020"
/// ```
///
/// ## Parameters
///
/// - `mapping`: A function that takes an edge reference and context, and returns a transformed value.
/// The function signature is `FnMut(Graph::EdgeReference<'graph>, Walker::Context) -> R`.
///
/// ## Return Value
///
/// Returns an iterator that yields the transformed elements, with the type determined by
/// the return type of the mapping function.
///
/// ## Example
///
/// ```rust
#[doc = function_body!("examples/map.rs", edge_example, [])]
/// ```
///
/// ## Notes
///
/// - Perfect for extracting relationship data (e.g., edge types, weights, or properties)
/// - Use pattern matching to handle different edge types appropriately
/// - You can access connected vertices through the edge's tail() and head() methods
/// - For analyzing graph connectivity, pair with edge-traversal steps like filter
/// - The iterator chain can continue with standard Rust iterator methods after mapping
pub fn map<R, M>(mut self, mut mapping: M) -> impl Iterator<Item = R> + 'graph
where
M: FnMut(Graph::EdgeReference<'graph>, Walker::Context) -> R + 'graph,
Walker: 'graph,
{
EdgeReferenceIterImpl::new(self.graph(), self.walker())
.map(move |(reference, ctx)| mapping(reference, ctx))
}
}